Oracle Fusion MiddlewareWeb User Interface Developer's Guide for Oracle Application Development Framework 11g Release 1 (11.1.1)B31973-03

May 2009

Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework, 11g Release 1 (11.1.1) B31973-03 Copyright 2009, Oracle and/or its affiliates. All rights reserved. Primary Authors: Robin Whitmore (lead), Peter Jew, Kathryn Munn Rosslynne Hefferen, Poh Lee Tan, Odile Sullivan-Tarazi, and Susan Shepard

Contributing Authors: Contributors:

ADF Faces development team, Frank Nimphius

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 software or related documentation 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 USA, Inc., 500 Oracle Parkway, Redwood City, CA 94065. This software 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 which may create a risk of personal injury. If you use this software in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure the safe use of this software. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software in dangerous applications. Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners. This software 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.

ContentsPreface ............................................................................................................................................................. xxiiiAudience................................................................................................................................................... Documentation Accessibility ................................................................................................................. Related Documents ................................................................................................................................. Conventions ............................................................................................................................................. xxiii xxiii xxiv xxiv

Part I 1

Getting Started with ADF Faces

Introduction to ADF Faces Rich Client1.1 1.1.1 1.1.2 1.2 1.2.1 1.2.1.1 1.2.1.2 1.2.2 1.3 1.4 1.4.1 1.4.2 1.4.3 Introduction to Oracle ADF Faces Rich Client ....................................................................... 1-1 History of ADF Faces .......................................................................................................... 1-2 ADF Faces as Rich Client Components ............................................................................ 1-2 Architecture of ADF Faces Components ................................................................................. 1-3 Client-Side Architecture ..................................................................................................... 1-3 Client-side Components .............................................................................................. 1-4 JavaScript Library Partitioning................................................................................... 1-4 ADF Faces Architectural Features..................................................................................... 1-5 ADF Faces Components............................................................................................................. 1-6 ADF Faces Demonstration Application................................................................................... 1-8 How to Download and Install the ADF Faces Demo Application ............................ 1-13 Overview of the File Explorer Application................................................................... 1-13 Viewing the Source Code In JDeveloper ....................................................................... 1-16

2

Getting Started with ADF Faces2.1 2.2 2.2.1 2.2.2 2.3 2.3.1 2.3.2 Developing Declaratively in JDeveloper ................................................................................. Creating an Application Workspace ........................................................................................ How to Create an Application Workspace ...................................................................... What Happens When You Create an Application Workspace ..................................... Defining Page Flows................................................................................................................... How to Define a Page Flow................................................................................................ What Happens When You Use the Diagrammer to Create a Page Flow .................... 2-1 2-2 2-2 2-3 2-5 2-6 2-7

iii

2.4 2.4.1 2.4.2 2.4.3 2.4.4 2.4.5 2.4.6 2.4.7 2.5 2.5.1 2.5.2 2.6 2.6.1 2.6.2 2.7

Creating a JSF Page ..................................................................................................................... 2-8 How to Create JSF Pages .................................................................................................... 2-9 What Happens When You Create a JSF Page ............................................................... 2-10 What You May Need to Know About Automatic Component Binding .................. 2-12 How to Add ADF Faces Components to JSF Pages..................................................... 2-15 What Happens When You Add Components to a Page ............................................. 2-17 How to Set Component Attributes................................................................................. 2-18 What Happens When You Use the Property Inspector .............................................. 2-20 Creating EL Expressions ......................................................................................................... 2-20 How to Create an EL Expression.................................................................................... 2-20 How to Use EL Expressions Within Managed Beans.................................................. 2-22 Creating and Using Managed Beans..................................................................................... 2-23 How to Create a Managed Bean in JDeveloper............................................................ 2-24 What Happens When You Use JDeveloper to Create a Managed Bean................... 2-25 Viewing ADF Faces Source Code and Javadoc ................................................................... 2-25

Part II 3

Understanding ADF Faces Architecture

Using ADF Faces Architecture3.1 3.2 3.3 3.3.1 3.3.2 3.3.3 3.4 3.5 3.5.1 3.6 3.6.1 3.6.2 3.6.3 3.7 3.7.1 3.7.2 3.8 3.8.1 3.8.2 Introduction to Using ADF Faces Architecture ...................................................................... 3-1 Listening for Client Events ........................................................................................................ 3-3 Adding JavaScript to a Page...................................................................................................... 3-4 How to Use Inline JavaScript ............................................................................................. 3-4 How to Import JavaScript Libraries .................................................................................. 3-5 What You May Need to Know About Accessing Client Event Sources ...................... 3-6 Instantiating Client-Side Components..................................................................................... 3-6 Locating a Client Component on a Page ................................................................................. 3-7 What You May Need to Know About Finding Components in Naming Containers ....... 3-8 Accessing Component Properties on the Client..................................................................... 3-9 How to Set Property Values on the Client ....................................................................... 3-9 What Happens at Runtime: How Client Properties Are Set on the Client............... 3-10 What You May Need to Know About Secured and Disconnected Properties ........ 3-10 Using Bonus Attributes for Client-Side Components ........................................................ 3-10 How to Create Bonus Attributes .................................................................................... 3-11 What You May Need to Know About Marshalling Bonus Attributes...................... 3-11 Understanding Rendering and Visibility ............................................................................. 3-11 How to Set Visibility Using JavaScript .......................................................................... 3-13 What You May Need to Know About Visible and the isShowing Function............ 3-14

4 Understanding the JSF and ADF Faces Lifecycles4.1 4.2 4.3 4.4 4.4.1 Introduction to the JSF and ADF Faces Lifecycles ................................................................. The JSF Lifecycle ......................................................................................................................... Using the Immediate Attribute ................................................................................................. Using the Optimized Lifecycle.................................................................................................. What You May Need to Know About Using the Immediate Attribute and the Optimized Lifecycle 4-10 4-1 4-1 4-4 4-9

iv

4.5 4.6 4.7 4.8 4.8.1 4.8.2 4.8.3

Using the Client-Side Lifecycle .............................................................................................. Using Subforms to Create Regions on a Page...................................................................... Object Scope Lifecycles ........................................................................................................... Passing Values Between Pages .............................................................................................. How to Use the pageFlowScope Scope Within Java Code ......................................... How to Use the pageFlowScope Scope Without Writing Java Code ........................ What Happens at Runtime: Passing Values .................................................................

4-11 4-12 4-13 4-14 4-15 4-16 4-16

5

Handling Events5.1 5.1.1 5.1.2 5.2 5.3 5.3.1 5.3.2 5.3.3 5.3.4 5.3.5 5.3.6 5.3.7 5.4 5.4.1 5.4.2 5.4.3 5.5 5.6 5.6.1 5.6.2 Introduction to Events and Event Handling........................................................................... 5-1 Events and Partial Page Rendering................................................................................... 5-2 Client-Side Event Model..................................................................................................... 5-3 Using ADF Faces Server Events................................................................................................ 5-3 Using JavaScript for ADF Faces Client Events ....................................................................... 5-5 How to Return the Original Source of the Event ............................................................ 5-9 Using Client-Side Attributes for an Event ....................................................................... 5-9 How to Block UI Input During Event Execution ......................................................... 5-10 How to Prevent Events from Propagating to the Server ............................................ 5-10 How to Trigger Event Handler Execution .................................................................... 5-11 What Happens at Runtime: How Client-Side Events Work ...................................... 5-12 What You May Need to Know About Using Naming Containers............................ 5-13 Sending Custom Events from the Client to the Server....................................................... 5-14 How to Send Custom Events from the Client to the Server ....................................... 5-15 What Happens at Runtime: How Client and Server Listeners Work Together ...... 5-16 What You May Need to Know About Marshalling and Unmarshalling of Data.... 5-16 Executing a Script Within an Event Response..................................................................... 5-18 Using Client Behavior Tags .................................................................................................... 5-20 How to Use the showPrintablePageBehavior Tag ....................................................... 5-20 How to Use the scrollComponentIntoViewBehavior Tag .......................................... 5-21

6 Validating and Converting Input6.1 6.2 6.3 6.3.1 6.3.2 6.3.3 6.4 6.4.1 6.4.2 6.5 6.5.1 6.5.1.1 6.5.1.2 6.5.1.3 6.5.2 Introduction to ADF Faces Converters and Validators......................................................... 6-1 Conversion, Validation, and the JSF Lifecycle........................................................................ 6-2 Adding Conversion .................................................................................................................... 6-2 How to Add a Converter .................................................................................................... 6-3 How to Set Attributes on a Converter .............................................................................. 6-4 What Happens at Runtime ................................................................................................. 6-4 Creating Custom JSF Converters .............................................................................................. 6-5 How to Create a Custom JSF Converter........................................................................... 6-5 What Happens When You Use a Custom Converter ..................................................... 6-8 Adding Validation ...................................................................................................................... 6-8 How to Add Validation ...................................................................................................... 6-8 Adding ADF Faces Validation.................................................................................... 6-8 Using Validation Attributes ........................................................................................ 6-9 Using ADF Faces Validators ....................................................................................... 6-9 What Happens at Runtime .............................................................................................. 6-10

v

6.5.3 6.6 6.6.1 6.6.2 6.6.3 6.6.4

What You May Need to Know About Multiple Validators........................................ Creating Custom JSF Validation............................................................................................ How to Create a Backing Bean Validation Method ..................................................... What Happens When You Create a Backing Bean Validation Method.................... How to Create a Custom JSF Validator ......................................................................... What Happens When You Use a Custom JSF Validator.............................................

6-11 6-11 6-11 6-12 6-12 6-14

7

Rerendering Partial Page Content7.1 7.2 7.2.1 7.2.2 7.2.3 7.3 7.4 7.4.1 7.4.2 Introduction to Partial Page Rendering................................................................................... Enabling Partial Page Rendering Declaratively ..................................................................... How to Enable Partial Page Rendering ............................................................................ What You May Need to Know About Using the Browser Back Button ...................... What You May Need to Know About PPR and Screen Readers .................................. Enabling Partial Page Rendering Programmatically ............................................................. Partial Page Navigation ............................................................................................................. How to Use Partial Page Navigation ................................................................................ What You May Need to Know About PPR Navigation................................................. 7-1 7-2 7-4 7-5 7-6 7-6 7-7 7-7 7-7

Part III

Using ADF Faces Components

8 Organizing Content on Web Pages8.1 8.2 8.2.1 8.2.2 8.2.3 8.2.4 8.2.5 8.3 8.3.1 8.3.2 8.4 8.4.1 8.4.2 8.5 8.6 8.6.1 8.6.2 8.7 8.7.1 8.7.2 8.8 8.8.1 Introduction to Organizing Content on Web Pages .............................................................. 8-1 Starting to Lay Out a Page......................................................................................................... 8-5 Geometry Management and Component Stretching ..................................................... 8-6 Nesting Components Inside Components That Allow Stretching ............................... 8-9 Using Quick Layouts........................................................................................................ 8-12 Tips for Using Geometry-Managed Components ....................................................... 8-12 How to Configure the document Tag............................................................................ 8-13 Arranging Contents to Stretch Across a Page...................................................................... 8-14 How to Use the panelStretchLayout Component ........................................................ 8-16 What You May Need to Know About Geometry Management and the panelStretchLayout Component 8-17 Using Splitters to Create Resizable Panes ............................................................................ 8-18 How to Use the panelSplitter Component .................................................................... 8-20 What You May Need to Know About Geometry Management and the panelSplitter Component 8-22 Arranging Page Contents in Predefined Areas ................................................................... 8-23 Arranging Content in Forms .................................................................................................. 8-26 How to Use the panelFormLayout Component........................................................... 8-27 What You May Need to Know About Using the group Component with the panelFormLayout Component 8-30 Arranging Contents in a Dashboard ..................................................................................... 8-34 How to Use the panelDashboard Component ............................................................. 8-36 What You May Need to Know About Geometry Management and the panelDashboard Component 8-39 Displaying and Hiding Contents Dynamically ................................................................... 8-39 How to Use the showDetail Component ...................................................................... 8-43

vi

8.8.2 8.8.3 8.8.4 8.9 8.9.1 8.9.2 8.9.3 8.9.4 8.9.5 8.10 8.10.1 8.11 8.11.1 8.11.2 8.12 8.12.1 8.12.2 8.13 8.13.1 8.13.2

How to Use the showDetailHeader Component ......................................................... 8-44 How to Use the panelBox Component .......................................................................... 8-46 What You May Need to Know About Disclosure Events........................................... 8-47 Displaying or Hiding Contents in Accordion Panels and Tabbed Panels....................... 8-48 How to Use the panelAccordion Component .............................................................. 8-51 How to Use the panelTabbed Component.................................................................... 8-51 How to Use the showDetailItem Component to Display Content in panelAccordion or panelTabbed Components 8-52 What You May Need to Know About Geometry Management and the showDetailItem Component 8-55 What You May Need to Know About showDetailItem Disclosure Events ............. 8-57 Displaying Items in a Content Container ............................................................................ 8-57 How to Use the panelHeader Component.................................................................... 8-59 Displaying a Bulleted List in One or More Columns ......................................................... 8-60 How to Use the panelList Component .......................................................................... 8-61 What You May Need to Know About Creating a List Hierarchy ............................. 8-62 Grouping Related Items .......................................................................................................... 8-63 How to Use the panelGroupLayout Component......................................................... 8-65 What You May Need to Know About Geometry Management and the panelGroupLayout Component 8-67 Separating Content Using Blank Space or Lines ................................................................. 8-67 How to Use the spacer Component ............................................................................... 8-68 How to Use the Separator Component.......................................................................... 8-68

9

Using Input Components and Defining Forms9.1 9.2 9.2.1 9.2.2 9.2.3 9.3 9.3.1 9.3.2 9.4 9.4.1 9.4.2 9.5 9.5.1 9.5.2 9.6 9.6.1 9.7 9.7.1 9.7.2 9.8 9.8.1 Introduction to Input Components and Forms ...................................................................... 9-1 Defining Forms............................................................................................................................ 9-3 How to Add a Form to a Page ........................................................................................... 9-5 How to Add a Subform to a Page...................................................................................... 9-5 How to Add a Reset Button to a Form ............................................................................. 9-5 Using the inputText Component .............................................................................................. 9-6 How to Add an inputText Component ............................................................................ 9-7 How to Add Ability to Insert Text into an inputText Component............................... 9-9 Using the Input Number Components .................................................................................... 9-9 How to Add an inputNumberSlider or an inputRangeSlider Component ............. 9-10 How to Add an inputNumberSpinbox Component.................................................... 9-11 Using Color and Date Choosers ............................................................................................ 9-11 How to Add an inputColor Component ....................................................................... 9-13 How to Add an InputDate Component ........................................................................ 9-14 Using Selection Components ................................................................................................. 9-15 How to Use Selection Components................................................................................ 9-18 Using Shuttle Components..................................................................................................... 9-20 How to Add a selectManyShuttle or selectOrderShuttle Component...................... 9-22 What You May Need to Know About Using a Client Listener for Selection Events ........ 9-23 Using the richTextEditor Component................................................................................... 9-25 How to Add Ability to Insert Text into a richTextEditor Component ..................... 9-27

vii

9.9 9.9.1 9.9.2

Using File Upload .................................................................................................................... 9-28 How to Use the inputFile Component........................................................................... 9-30 What You May Need to Know About Temporary File Storage................................. 9-31

10

Using Tables and Trees10.1 Introduction to Tables, Trees, and Tree Tables ................................................................... 10-1 10.1.1 Content Delivery............................................................................................................... 10-4 10.1.2 Row Selection .................................................................................................................... 10-5 10.1.3 Editing Data in Tables, Trees, and Tree Tables ............................................................ 10-5 10.1.4 Using Popup Dialogs in Tables, Trees, and Tree Tables............................................. 10-7 10.1.5 Accessing Client Table, Tree, and Tree Table Components ....................................... 10-9 10.2 Displaying Data in Tables....................................................................................................... 10-9 10.2.1 Columns and Column Data .......................................................................................... 10-10 10.2.2 Formatting Tables ........................................................................................................... 10-11 10.2.3 Formatting Columns ...................................................................................................... 10-12 10.2.4 How to Display a Table on a Page ............................................................................... 10-13 10.2.5 What Happens When You Add a Table to a Page ..................................................... 10-19 10.2.6 What Happens at Runtime ............................................................................................ 10-20 10.2.7 What You May Need to Know About Programmatically Enabling Sorting for Table Columns 10-21 10.2.8 What You May Need to Know About Performing an Action on Selected Rows in Tables 10-21 10.2.9 What You May Need to Know About Dynamically Determining Values for Selection Components in Tables 10-22 10.2.10 What You May Need to Know About Using the Iterator Tag ................................. 10-23 10.3 Adding Hidden Capabilities to a Table.............................................................................. 10-24 10.3.1 How to Use the detailStamp Facet ............................................................................... 10-25 10.3.2 What Happens at Runtime ............................................................................................ 10-26 10.4 Enabling Filtering in Tables.................................................................................................. 10-26 10.4.1 How to Add Filtering to a Table................................................................................... 10-27 10.5 Displaying Data in Trees....................................................................................................... 10-28 10.5.1 How to Display Data in Trees....................................................................................... 10-30 10.5.2 What Happens When You Add a Tree to a Page....................................................... 10-32 10.5.3 What Happens at Runtime ............................................................................................ 10-33 10.5.4 What You May Need to Know About Programmatically Expanding and Collapsing Nodes 10-33 10.5.5 What You May Need to Know About Programmatically Selecting Nodes ........... 10-35 10.6 Displaying Data in Tree Tables............................................................................................ 10-35 10.6.1 How to Display Data in a Tree Table........................................................................... 10-37 10.7 Passing a Row as a Value...................................................................................................... 10-37 10.8 Displaying Table Menus, Toolbars, and Status Bars ........................................................ 10-38 10.8.1 How to Add a panelCollection with a Table, Tree, or Tree Table ........................... 10-40 10.9 Exporting Data from Table, Tree, or Tree Table................................................................ 10-40 10.9.1 How to Export Table, Tree, or Tree Table Data to an External Format .................. 10-42 10.9.2 What Happens at Runtime: How Row Selection Affects the Exported Data ........ 10-43 10.10 Accessing Selected Values on the Client From Components that Use Stamping ........ 10-43 10.10.1 How to Access Values From a Selection in Stamped Components......................... 10-44 10.10.2 What You May Need to Know About Accessing Selected Values .......................... 10-46

viii

11

Using List-of-Values Components11.1 11.2 11.3 11.4 Introduction to List-of-Values Components ........................................................................ Creating the ListOfValues Data Model................................................................................. Using the inputListOfValues Component............................................................................ Using the InputComboboxListOfValues Component ........................................................ 11-1 11-5 11-7 11-8

12 Using Query Components12.1 Introduction to Query Components...................................................................................... 12-1 12.2 Implementing the Model for Your Query ............................................................................ 12-3 12.3 Using the quickQuery Component ..................................................................................... 12-10 12.3.1 How to Add the quickQuery Component Using a Model ....................................... 12-11 12.3.2 How to Use a quickQuery Component Without a Model ........................................ 12-12 12.3.3 What Happens at Runtime: How the Framework Renders the quickQuery Component and Executes the Search 12-13 12.4 Using the query Component ................................................................................................ 12-13 12.4.1 How to Add the Query Component ............................................................................ 12-17

13 Using Popup Dialogs, Menus, and Windows13.1 Introduction to Using Popup Elements ................................................................................ 13.2 Creating Popup Elements ....................................................................................................... 13.2.1 Showing and Hiding Popup Elements .......................................................................... 13.2.2 Delivering Content to the Client..................................................................................... 13.2.3 Using Dialog Buttons ....................................................................................................... 13.2.4 How to Create a Dialog.................................................................................................... 13.2.5 How to Create a Panel Window ..................................................................................... 13.2.6 How to Create a Context Menu ...................................................................................... 13.3 Using Command Components to Show Popup Elements................................................. 13.3.1 How to Use the af:showPopupBehavior Tag ............................................................... 13.4 External Browser Window ..................................................................................................... 13.4.1 How to Create External Dialogs and Page Flows ...................................................... 13.4.1.1 Defining a JSF Navigation Rule for Opening a Dialog ...................................... 13.4.1.2 Creating the JSF Page That Opens a Dialog ........................................................ 13.4.1.3 Creating the Dialog Page and Returning a Dialog Value.................................. 13.4.1.4 Passing a Value into a Dialog ................................................................................ 13.4.1.5 Handling the Return Value .................................................................................... 13-1 13-2 13-3 13-3 13-4 13-4 13-5 13-6 13-6 13-7 13-9 13-11 13-12 13-13 13-14 13-17 13-18

14

Using Menus, Toolbars, and Toolboxes14.1 Introduction to Menus, Toolbars, and Toolboxes ............................................................... 14.2 Using Menus in a Menu Bar................................................................................................... 14.2.1 How to Create and Use Menus in a Menu Bar............................................................. 14.3 Using Toolbars ....................................................................................................................... 14.3.1 How to Create and Use Toolbars ................................................................................. 14.3.2 What Happens at Runtime: Determining the Size of Toolbars................................ 14.3.3 What You May Need to Know About Toolbars......................................................... 14-1 14-2 14-6 14-11 14-12 14-16 14-16

ix

15

Creating a Calendar Application15.1 15.2 15.2.1 15.2.2 15.3 15.3.1 15.3.2 15.4 15.4.1 15.5 15.5.1 15.5.2 15.6 15.6.1 15.7 15.7.1 15.7.2 15.7.3 Introduction to Creating a Calendar Application ............................................................... Creating the Calendar ............................................................................................................. Calendar Classes ............................................................................................................... How to Create a Calendar ............................................................................................... Configuring the Calendar Component................................................................................. How to Configure the Calendar Component ............................................................... What Happens at Runtime: Calendar Events and PPR .............................................. Adding Functionality Using Popup Components .............................................................. How to Add Functionality Using Popup Components .............................................. Adding Drag and Drop Functionality to a Calendar ....................................................... How to Add Drag and Drop Functionality to a Calendar........................................ What You May Need to Know About Dragging and Dropping in a Calendar..... Customizing the Toolbar ...................................................................................................... How to Customize the Toolbar..................................................................................... Styling the Calendar .............................................................................................................. How to Style Activities .................................................................................................. What Happens at Runtime: Activity Styling .............................................................. How to Customize Dates............................................................................................... 15-1 15-4 15-4 15-5 15-6 15-6 15-8 15-8 15-9 15-12 15-12 15-13 15-13 15-14 15-16 15-16 15-18 15-18

16 Using Output Components16.1 Introduction to Output Text, Image, Icon, and Media Components ............................... 16-1 16.2 Displaying Output Text and Formatted Output Text ........................................................ 16-2 16.2.1 How to Display Output Text .......................................................................................... 16-3 16.2.2 What You May Need to Know About Allowed Format and Character Codes in the outputFormatted Component 16-4 16.3 Displaying Icons....................................................................................................................... 16-5 16.4 Displaying Images ................................................................................................................... 16-5 16.5 Using Images as Links............................................................................................................. 16-6 16.6 Displaying Application Status Using Icons ......................................................................... 16-7 16.7 Playing Video and Audio Clips ............................................................................................. 16-8 16.7.1 Media Players .................................................................................................................... 16-8 16.7.2 Display Size ....................................................................................................................... 16-8 16.7.3 Controls .............................................................................................................................. 16-9 16.7.4 Automatic Start and Repeated Play ............................................................................... 16-9 16.7.5 How to Play Audio and Video Clips ........................................................................... 16-10

17

Displaying Tips, Messages, and Help17.1 17.2 17.3 17.3.1 17.3.2 17.3.3 17.3.4 17.4 Introduction to Displaying Tips and Messages................................................................... Displaying Tips for Components .......................................................................................... Displaying Hints and Error Messages for Validation and Conversion ........................... How to Define Custom Validator and Converter Messages...................................... What You May Need to Know About Overriding Default Messages Globally ...... How to Display Component Messages Inline .............................................................. How to Display Global Messages Inline ....................................................................... Grouping Components with a Single Label and Message................................................. 17-1 17-5 17-5 17-7 17-8 17-8 17-9 17-9

x

17.5 Displaying Help for Components ....................................................................................... 17.5.1 How to Create Resource Bundle-Based Help............................................................. 17.5.2 How to Create XLIFF-Based Help................................................................................ 17.5.3 How to Create Managed Bean Help ............................................................................ 17.5.4 How to Create a Java Class Help Provider ................................................................. 17.5.5 How to Access Help Content from a UI Component................................................ 17.5.6 What You May Need to Know About Combining Different Message Types .......

17-11 17-14 17-16 17-18 17-20 17-22 17-22

18 Working with Navigation Components18.1 18.2 18.2.1 18.2.2 18.3 18.3.1 18.3.2 18.4 18.5 18.5.1 18.5.2 18.6 18.6.1 18.6.2 18.6.3 18.6.4 18.6.5 18.6.6 18.7 18.7.1 18.7.2 18.7.3 Introduction to Navigation Components ............................................................................. Using Buttons and Links for Navigation.............................................................................. How to Use Command Buttons and Command Links ............................................... How to Use Go Buttons and Go Links .......................................................................... Using Buttons or Links to Invoke Functionality ................................................................. How to Use a Command Component to Download Files .......................................... How to Use a Command Component to Reset Input Fields ...................................... Using Navigation Items for a Page Hierarchy..................................................................... Creating a Simple Navigational Hierarchy........................................................................ How to Create a Simple Page Hierarchy..................................................................... How to Use the breadCrumbs Component ................................................................ Using a Menu Model to Create a Page Hierarchy............................................................. How to Create the Menu Model Metadata ................................................................. What Happens When You Use the Create ADF Menu Model Wizard .................. How to Bind to the XMLMenuModel in the JSF Page .............................................. How to Use the breadCrumbs Component ................................................................ What Happens at Runtime ............................................................................................ What You May Need to Know About Using Custom Attributes............................ Using Train Components to Create Navigation Items for a Multi-Step Process.......... How to Create the Train Model.................................................................................... How to Configure Managed Beans for the Train Model .......................................... How to Bind to the Train Model in JSF Pages ............................................................ 18-1 18-2 18-2 18-4 18-5 18-5 18-7 18-7 18-11 18-12 18-15 18-16 18-18 18-25 18-26 18-30 18-31 18-33 18-35 18-38 18-40 18-44

19 Creating and Reusing Fragments, Templates, and Components19.1 Introduction to Reusable Content ......................................................................................... 19.2 Using Page Fragments............................................................................................................. 19.2.1 How to Create a Page Fragment..................................................................................... 19.2.2 What Happens When You Create a Page Fragment.................................................... 19.2.3 How to Use a Page Fragment in a JSF Page.................................................................. 19.2.4 What Happens at Runtime: Resolving Page Fragments ............................................. 19.3 Using Page Templates ............................................................................................................. 19.3.1 How to Create a Page Template ................................................................................... 19.3.2 What Happens When You Create a Page Template .................................................. 19.3.3 How to Create JSF Pages Based on Page Templates.................................................. 19.3.4 What Happens When You Use a Template to Create a Page................................... 19.3.5 What Happens at Runtime: How Page Templates Are Resolved ........................... 19.3.6 What You May Need to Know About Templates and Naming Containers .......... 19-1 19-2 19-5 19-6 19-7 19-7 19-7 19-11 19-15 19-15 19-17 19-18 19-18

xi

19.4 Using Declarative Components ........................................................................................... 19.4.1 How to Create a Declarative Component ................................................................... 19.4.2 What Happens When You Create a Declarative Component .................................. 19.4.3 How to Deploy Declarative Components ................................................................... 19.4.4 How to Use Declarative Components in JSF Pages ................................................... 19.4.5 What Happens When You Use a Declarative Component on a JSF Page .............. 19.4.6 What Happens at Runtime ............................................................................................ 19.5 Adding Resources to Templates and Declarative Components ..................................... 19.5.1 How to Add Resources to Templates and Declarative Components...................... 19.5.2 What Happens at Runtime: Adding Resources to the Document Header.............

19-18 19-21 19-25 19-27 19-28 19-29 19-30 19-30 19-31 19-31

20 Customizing the Appearance Using Styles and Skins20.1 Introduction to Skins, Style Selectors, and Style Properties .............................................. 20.1.1 Oracle ADF Faces Skins ................................................................................................... 20.1.2 Skin Style Selectors ........................................................................................................... 20.1.3 Component Style Properties ........................................................................................... 20.2 Applying Custom Skins to Applications.............................................................................. 20.2.1 How to Add a Custom Skin to an Application .......................................................... 20.2.2 How to Register a Custom Skin.................................................................................... 20.2.3 How to Configure an Application to Use a Custom Skin......................................... 20.2.4 How to Deploy a Custom Skin into a JAR file ........................................................... 20.3 Defining Skin Style Properties ............................................................................................. 20.3.1 How to Apply Skins to Text .......................................................................................... 20.3.2 How to Apply Skins to Icons ........................................................................................ 20.3.3 How to Apply Skins to Messages................................................................................. 20.3.4 How to Apply Themes to Components....................................................................... 20.3.4.1 What You May Need to Know About Tonal Styles............................................ 20.3.4.2 What You May Need to Know About Theme Inheritance ................................ 20.3.5 How to Create a Custom Alias ..................................................................................... 20.3.6 How to Configure a Component for Changing Skins Dynamically ....................... 20.4 Changing the Style Properties of a Component ............................................................... 20.4.1 How to Set an Inline Style ............................................................................................. 20.4.2 How to Set a Style Class................................................................................................. 20-1 20-2 20-5 20-8 20-9 20-10 20-11 20-14 20-15 20-17 20-18 20-20 20-21 20-21 20-22 20-22 20-23 20-23 20-24 20-24 20-26

21 Internationalizing and Localizing Pages21.1 21.2 21.2.1 21.2.2 21.2.3 21.2.4 21.2.5 21.3 21.3.1 21.4 21.4.1 Introduction to Internationalization and Localization of ADF Faces Pages ................... Defining Locales and Resource Bundles .............................................................................. How to Define the Base Resource Bundle..................................................................... How to Edit a Resource Bundle File .............................................................................. How to Register Locales and Resource Bundles in Your Application...................... How to Use Resource Bundles in Your Application ................................................. What You May Need to Know About Custom Skins and Control Hints............... Using Automatic Resource Bundle Integration in JDeveloper ....................................... How to Set Resource Bundle Options.......................................................................... Configuring Optional ADF Faces Localization Properties .............................................. How to Configure Optional Localization Properties ................................................ 21-1 21-3 21-4 21-7 21-8 21-10 21-11 21-11 21-12 21-13 21-14

xii

22 Developing Accessible ADF Faces Pages22.1 22.2 22.2.1 22.2.2 22.2.3 22.2.4 22.2.5 22.2.6 22.3 22.3.1 22.3.2 22.4 22.4.1 22.5 22.5.1 22.5.2 22.5.3 22.5.4 Introduction to Accessible ADF Faces Pages ....................................................................... Developing Accessible ADF Faces Components and Pages.............................................. Using ADF Faces Component Accessibility Guidelines ............................................. How to Run an ADF Faces Accessibility Rules Audit ................................................ How to Use Partial Page Rendering .............................................................................. How to Use Scripting ....................................................................................................... How to Use Styles............................................................................................................. How to Use Page Structures and Navigation............................................................... Defining Access Keys for ADF Faces Components ............................................................ How to Define Access Keys for an ADF Faces Component ....................................... How to Define Localized Labels and Access Keys ...................................................... Selecting Accessibility Modes .............................................................................................. How to Configure Accessibility Support in trinidad-config.xml ............................ Providing Text For Screen Reader Support ....................................................................... How to Provide Screen Reader Support for Images, Icons and Other Objects ..... How to Provide Screen Reader Support for Frames ................................................. How to Provide Screen Reader Support for Tables ................................................... How to Provide Screen Reader Support for Text....................................................... 22-1 22-2 22-2 22-4 22-5 22-5 22-6 22-6 22-7 22-8 22-9 22-10 22-10 22-11 22-11 22-11 22-12 22-13

Part IV

Using ADF Data Visualization Components

23 Introduction to ADF Data Visualization Components23.1 23.2 23.2.1 23.2.2 23.2.3 23.2.4 23.2.5 23.2.6 23.3 23.4 Introducing ADF Data Visualization Components ............................................................ Defining the ADF Data Visualization Components ........................................................... Graph .................................................................................................................................. Gauge.................................................................................................................................. Pivot Table ......................................................................................................................... Geographic Map ............................................................................................................... Gantt Chart ........................................................................................................................ Hierarchy Viewer.............................................................................................................. Providing Data for ADF Data Visualization Components ................................................ Downloading Custom Fonts for Flash Images .................................................................... 23-1 23-1 23-1 23-4 23-6 23-6 23-7 23-8 23-9 23-9

24 Using ADF Graph Components24.1 Introduction to the Graph Component................................................................................. 24.2 Understanding the Graph Tags ............................................................................................. 24.2.1 Graph-Specific Tags ......................................................................................................... 24.2.2 Common Graph Child Tags ............................................................................................ 24.2.3 Graph-Specific Child Tags............................................................................................... 24.2.4 Child Set Tags.................................................................................................................... 24.3 Understanding Data Requirements for Graphs .................................................................. 24.3.1 Area Graphs Data Requirements.................................................................................... 24.3.2 Bar Graph Data Requirements........................................................................................ 24.3.3 Bubble Graph Data Requirements ................................................................................. 24.3.4 Combination Graph Data Requirements....................................................................... 24-1 24-2 24-3 24-4 24-5 24-5 24-6 24-7 24-7 24-8 24-8

xiii

24.3.5 Funnel Graph Data Requirements ................................................................................. 24.3.6 Line Graph Data Requirements ...................................................................................... 24.3.7 Pareto Graph Data Requirements .................................................................................. 24.3.8 Pie Graph Data Requirements ...................................................................................... 24.3.9 Polar Graph Data Requirements .................................................................................. 24.3.10 Radar Graph Data Requirements ................................................................................. 24.3.11 Scatter Graph Data Requirements................................................................................ 24.3.12 Stock Graph Data Requirements .................................................................................. 24.3.12.1 Stock Graphs: High-Low-Close ............................................................................. 24.3.12.2 Stock Graphs: High-Low-Close with Volume..................................................... 24.3.12.3 Stock Graphs: Open-High-Low-Close.................................................................. 24.3.12.4 Stock Graphs: Open-High-Low-Close with Volume.......................................... 24.3.12.5 Candle Stock Graphs: Open-Close ....................................................................... 24.3.12.6 Candle Stock Graphs: Open-Close with Volume ............................................... 24.3.12.7 Candle Stock Graphs: Open-High-Low-Close ................................................... 24.3.12.8 Candle Stock Graphs: Open-High-Low-Close with Volume ........................... 24.4 Creating a Graph ................................................................................................................... 24.4.1 How to Create a Graph Using Tabular Data ............................................................. 24.4.1.1 Storing Tabular Data for a Graph in a Managed Bean....................................... 24.4.1.2 Creating a Graph Using Tabular Data.................................................................. 24.4.2 What Happens When You Create a Graph Using Tabular Data ............................. 24.5 Customizing Common Graph Features.............................................................................. 24.5.1 Changing the Color and Style of Graph Bars, Lines, Areas, Points, and Slices..... 24.5.1.1 How to Specify the Color and Style for Individual Series Items...................... 24.5.1.2 How to Control the Number of Different Colors Used for Series Items ......... 24.5.2 Formatting Numbers in Graphs ................................................................................... 24.5.2.1 How to Format Numbers in the Y1-Axis of a Graph ......................................... 24.5.2.2 What Happens When You Format the Numbers in the Y1-Axis of a Graph.. 24.5.2.3 How to Format Numbers for the Marker Text of a Graph ............................... 24.5.2.4 What Happens When You Format Numbers in the Marker Text of a Graph 24.5.3 Formatting Text in Graphs ............................................................................................ 24.5.4 Changing Graph Size and Style ................................................................................... 24.5.4.1 How to Specify the Size of a Graph at Initial Display........................................ 24.5.4.2 How to Provide for Dynamic Resizing of a Graph............................................. 24.5.4.3 How to Use a Specific Style Sheet for a Graph.................................................... 24.5.5 Changing Graph Background, Plot Area, and Title .................................................. 24.5.5.1 How to Customize the Background and Plot Area of a Graph ........................ 24.5.5.2 How to Specify Titles and Footnotes in a Graph ................................................ 24.5.6 Customizing Graph Axes and Labels .......................................................................... 24.5.6.1 How to Specify the Title, Appearance, and Scaling of an Axis ........................ 24.5.6.2 How to Control the Appearance of Tick Marks and Labels on an Axis.......... 24.5.6.3 How to Format Numbers on an Axis ................................................................... 24.5.6.4 How to Set Minimum and Maximum Values on a Data Axis .......................... 24.5.7 Customizing Graph Legends ........................................................................................ 24.5.8 Customizing Tooltips in Graphs .................................................................................. 24.6 Customizing the Appearance of Specific Graph Types ................................................... 24.6.1 Changing the Type of Graphs.......................................................................................

24-9 24-9 24-9 24-10 24-10 24-10 24-11 24-11 24-11 24-12 24-12 24-12 24-12 24-12 24-13 24-13 24-13 24-13 24-14 24-15 24-15 24-16 24-16 24-16 24-17 24-17 24-17 24-18 24-18 24-18 24-19 24-19 24-19 24-19 24-20 24-20 24-20 24-21 24-22 24-22 24-23 24-24 24-24 24-24 24-25 24-26 24-26

xiv

24.6.2 Changing the Appearance of Pie Graphs.................................................................... 24.6.2.1 How to Customize the Overall Appearance of Pie Graphs .............................. 24.6.2.2 How to Specify an Exploding Pie Slice ................................................................ 24.6.3 Changing the Appearance of Line Graphs ................................................................. 24.6.3.1 How to Display Either Data Lines or Markers in a Line Graph ....................... 24.6.3.2 How to Change the Appearance of Lines in a Graph Series............................. 24.6.4 Customizing Pareto Graphs .......................................................................................... 24.7 Adding Specialized Features to Graphs ............................................................................. 24.7.1 Adding Reference Lines or Areas to Graphs .............................................................. 24.7.1.1 How to Create Reference Lines or Areas During Design .................................. 24.7.1.2 What Happens When You Create Reference Lines or Areas During Design. 24.7.1.3 How to Create Reference Lines or Areas Dynamically...................................... 24.7.2 Using Gradient Special Effects in Graphs ................................................................... 24.7.2.1 How to Add Gradient Special Effects to a Graph............................................... 24.7.2.2 What Happens When You Add a Gradient Special Effect to a Graph ............ 24.7.3 Specifying Transparent Colors for Parts of a Graph ................................................. 24.7.4 Providing Interactive Capability for Graphs .............................................................. 24.7.4.1 How to Provide Marker and Legend Dimming.................................................. 24.7.4.2 How to React to Changes in the Zoom and Scroll Levels ................................. 24.7.5 Providing an Interactive Time Axis for Graphs ......................................................... 24.7.5.1 How to Define a Relative Range of Time Data for Display............................... 24.7.5.2 How to Define an Explicit Range of Time Data for Display ............................. 24.7.6 Adding Alerts and Annotations to Graphs................................................................. 24.8 Animating Graphs with Active Data .................................................................................. 24.8.1 How to Configure Graph Components to Display Active Data.............................. 24.8.2 How to Add Animation Effects that Use Active Data ..............................................

24-26 24-26 24-27 24-27 24-27 24-27 24-28 24-28 24-28 24-29 24-30 24-30 24-31 24-31 24-32 24-32 24-33 24-33 24-33 24-34 24-34 24-34 24-35 24-35 24-35 24-36

25 Using ADF Gauge Components25.1 Introduction to the Gauge Component ................................................................................ 25.1.1 Types of Gauges................................................................................................................ 25.1.2 Gauge Terminology.......................................................................................................... 25.2 Understanding Data Requirements for Gauges .................................................................. 25.3 Creating a Gauge...................................................................................................................... 25.3.1 Creating a Gauge Using Tabular Data........................................................................... 25.3.1.1 Storing Tabular Data for a Gauge in a Managed Bean ........................................ 25.3.1.2 Structure of the List of Tabular Data ...................................................................... 25.3.2 How to Create a Gauge Using Tabular Data ................................................................ 25.3.3 What Happens When You Create a Gauge Using Tabular Data............................... 25.4 Customizing Gauge Type, Layout, and Appearance ......................................................... 25.4.1 Changing the Type of the Gauge.................................................................................... 25.4.2 Determining the Layout of Gauges in a Gauge Set ..................................................... 25.4.3 Changing Gauge Size and Style...................................................................................... 25.4.3.1 How to Specify the Size of a Gauge at Initial Display ......................................... 25.4.3.2 How to Provide Dynamic Resizing of a Gauge .................................................... 25.4.3.3 How to Use a Custom Style Class for a Gauge ................................................... 25.4.4 Adding Thresholds to Gauges ...................................................................................... 25.4.4.1 How to Add Static Thresholds to Gauges ........................................................... 25-1 25-3 25-4 25-5 25-5 25-6 25-6 25-7 25-7 25-8 25-8 25-8 25-8 25-9 25-9 25-9 25-10 25-10 25-10

xv

25.4.4.2 What You May Need to Know About Adding Thresholds to Gauges............ 25.4.5 Formatting Numbers in Gauges ................................................................................... 25.4.5.1 How to Format the Number in a Gauge Metric Label ....................................... 25.4.5.2 What Happens When You Format the Number in a Gauge Metric Label...... 25.4.6 Formatting Text in Gauges ............................................................................................ 25.4.6.1 How to Format Text in a Gauge Metric Label..................................................... 25.4.6.2 What Happens When You Format Text in a Gauge Metric Label.................... 25.4.7 Specifying an N-Degree Dial......................................................................................... 25.4.8 Customizing Gauge Labels ........................................................................................... 25.4.8.1 How to Control the Position of Gauge Labels..................................................... 25.4.8.2 How to Customize the Colors and Borders of Gauge Labels ........................... 25.4.9 Customizing Indicators and Tick Marks ..................................................................... 25.4.9.1 How to Control the Appearance of Gauge Indicators ....................................... 25.4.9.2 How to Specify Tick Marks and Labels ............................................................... 25.4.9.3 How to Create Exterior Tick Labels ...................................................................... 25.5 Adding Gauge Special Effects and Animation .................................................................. 25.5.1 Using Gradient Special Effects in a Gauge.................................................................. 25.5.1.1 How to Add Gradient Special Effects to a Gauge............................................... 25.5.1.2 What Happens When You Add a Gradient Special Effect to a Gauge ............ 25.5.2 Animating Gauges.......................................................................................................... 25.5.3 Animating Gauges with Active Data........................................................................... 25.5.3.1 How to Configure Graph Components to Display Active Data....................... 25.5.3.2 How to Add Animation to Gauges....................................................................... 25.6 Using Custom Shapes in Gauges......................................................................................... 25.6.1 Creating a Custom Shapes Graphic File...................................................................... 25.6.2 How to Use a Custom Shapes File ............................................................................... 25.6.3 What You May Need to Know About Supported SVG Features ............................ 25.6.4 How to Set Custom Shapes Styles................................................................................

25-11 25-11 25-11 25-12 25-12 25-12 25-13 25-13 25-13 25-13 25-13 25-14 25-14 25-14 25-15 25-15 25-15 25-16 25-16 25-17 25-17 25-18 25-18 25-18 25-18 25-21 25-21 25-22

26 Using ADF Pivot Table Components26.1 26.1.1 26.2 26.3 26.4 26.5 26.6 26.6.1 26.6.2 26.6.3 26.7 26.8 26.8.1 26.8.2 26.8.3 26.8.4 26.9 Introduction tothe ADF Pivot Table Component................................................................ Pivot Table Elements and Terminology ........................................................................ Understanding Data Requirements for a Pivot Table ........................................................ Pivoting Layers......................................................................................................................... Selection in a Pivot Table ........................................................................................................ Sorting in a Pivot Table ........................................................................................................... Sizing in a Pivot Table ............................................................................................................. How to Set the Overall Size of a Pivot Table ................................................................ How to Resize Rows, Columns, and Layers ................................................................. What You May Need to Know About Resizing Rows, Columns and Layers ......... Connecting Pivot Tables with Other Components ............................................................. Customizing the Cell Content of a Pivot Table ................................................................... How to Create a CellFormat Object for a Data Cell..................................................... Constructing a CellFormat Object .................................................................................. Changing Format and Text Styles .................................................................................. Creating Stoplight and Conditional Formatting in a Pivot Table ............................ Pivot Table Data Cell Stamping and Editing ..................................................................... 26-1 26-2 26-3 26-3 26-4 26-5 26-5 26-5 26-6 26-6 26-6 26-7 26-7 26-8 26-8 26-9 26-10

xvi

26.9.1

Specifying Custom Images for Data Cells................................................................... 26-11

27

Using ADF Geographic Map Components27.1 Introduction toGeographic Maps .......................................................................................... 27.1.1 Available Map Themes .................................................................................................... 27.1.2 Geographic Map Terminology ....................................................................................... 27.1.3 Geographic Map Component Tags ................................................................................ 27.1.3.1 Geographic Map Parent Tags .................................................................................. 27.1.3.2 Geographic Map Child Tags .................................................................................... 27.1.3.3 Tags for Modifying Map Themes............................................................................ 27.2 Understanding Data Requirements for Geographic Maps ................................................ 27.3 Customizing Map Size, Zoom Control, and Selection Area Totals .................................. 27.3.1 How to Adjust the Map Size ........................................................................................... 27.3.2 How to Specify Strategy for Map Zoom Control ......................................................... 27.3.3 How to Total Map Selection Values............................................................................... 27.4 Customizing Map Themes...................................................................................................... 27.4.1 How to Customize Zoom Levels for a Theme.............................................................. 27.4.2 How to Customize the Labels of a Map Theme ........................................................... 27.4.3 How to Customize Color Map Themes ......................................................................... 27.4.4 Customizing Point Images in a Point Theme ............................................................. 27.4.4.1 How to Customize Point Images........................................................................... 27.4.4.2 What Happens When You Customize the Point Images in a Map .................. 27.4.5 Customizing the Bars in a Bar Graph Theme ............................................................. 27.4.5.1 How to Customize the Bars in a Map Bar Graph Theme .................................. 27.4.5.2 What Happens When You Customize the Bars in a Map Bar Graph Theme . 27.4.6 Customizing the Slices in a Pie Graph Theme............................................................ 27.4.6.1 How to Customize the Slices in a Map Pie Graph Theme................................. 27.4.6.2 What Happens When You Customize the Slices in a Map Pie Graph Theme 27.5 Adding a Toolbar to a Map .................................................................................................. 27.5.1 How to Add a Toolbar to a Map .................................................................................. 27.5.2 What Happens When You Add a Toolbar to a Map ................................................. 27-1 27-1 27-2 27-4 27-5 27-5 27-5 27-6 27-6 27-6 27-7 27-7 27-8 27-8 27-9 27-9 27-10 27-10 27-10 27-11 27-11 27-12 27-12 27-12 27-13 27-14 27-14 27-14

28 Using ADF Gantt Chart Components28.1 Introduction to the ADF Gantt Chart Components ............................................................ 28.1.1 Types of Gantt Charts ...................................................................................................... 28.1.2 Functional Areas of a Gantt Chart ................................................................................. 28.1.3 Description of Gantt Chart Tasks ................................................................................... 28.2 Understanding Gantt Chart Tags and Facets....................................................................... 28.3 Understanding Gantt Chart User Interactivity.................................................................... 28.3.1 Navigating in a Gantt Chart............................................................................................ 28.3.1.1 Scrolling the List Region or the Chart Region....................................................... 28.3.1.2 How to Navigate to a Specific Date in a Gantt Chart........................................... 28.3.1.3 How to Control the Visibility of Columns in the Table Region.......................... 28.3.2 How to Display Data in a Hierarchical List or a Flat List........................................... 28.3.3 How to Change the Gantt Chart Time Scale................................................................. 28.4 Understanding Data Requirements for the Gantt Chart ................................................... 28-1 28-2 28-3 28-4 28-5 28-6 28-7 28-7 28-7 28-8 28-8 28-8 28-9

xvii

28.4.1 Data for a Project Gantt Chart......................................................................................... 28.4.2 Data for a Resource Utilization Gantt Chart............................................................... 28.4.3 Data for a Scheduling Gantt Chart ............................................................................... 28.5 Creating an ADF Gantt Chart .............................................................................................. 28.6 Customizing Gantt Chart Legends, Toolbars, and Context Menus ............................... 28.6.1 How to Customize a Gantt Chart Legend................................................................... 28.6.2 Customizing Gantt Chart Toolbars .............................................................................. 28.6.3 Customizing Gantt Chart Context Menus .................................................................. 28.7 Working with Gantt Chart Tasks and Resources .............................................................. 28.7.1 How to Create a New Task Type ................................................................................. 28.7.2 How to Specify Custom Data Filters............................................................................ 28.7.3 How to Add a Double-Click Event to a Task Bar ...................................................... 28.8 Specifying Nonworking Days, Read-Only Features, and Time Axes ............................ 28.8.1 Identifying Nonworking Days in a Gantt Chart ........................................................ 28.8.1.1 How to Specify Weekdays as Nonworking Days............................................... 28.8.1.2 How to Identify Specific Dates as Nonworking Days ....................................... 28.8.2 How to Apply Read-Only Values to Gantt Chart Features...................................... 28.8.3 Customizing the Time Axis of a Gantt Chart ............................................................. 28.9 Printing a Gantt Chart ........................................................................................................... 28.9.1 Print Options ................................................................................................................... 28.9.2 Action Listener to Handle the Print Event.................................................................. 28.10 Using Gantt Charts as a Drop Target or Drag Source ......................................................

28-9 28-10 28-11 28-12 28-13 28-13 28-13 28-14 28-16 28-16 28-17 28-17 28-18 28-18 28-18 28-19 28-19 28-20 28-21 28-21 28-22 28-23

29

Using ADF Hierarchy Viewer Components29.1 Introduction to Hierarchy Viewers ....................................................................................... 29-1 29.1.1 Understanding the Hierarchy Viewer Component ..................................................... 29-1 29.1.2 Hierarchy Viewer Elements and Terminology............................................................. 29-2 29.1.3 Available Hierarchy Viewer Layout Options............................................................... 29-5 29.2 Data Requirements for Hierarchy Viewers .......................................................................... 29-5 29.3 Navigating in a Hierarchy Viewer ........................................................................................ 29-6 29.3.1 How to Configure Upward Navigation in a Hierarchy Viewer ................................ 29-6 29.3.2 How to Configure Same-Level Navigation in a Hierarchy Viewer .......................... 29-6 29.3.3 What Happens When You Configure Same-Level Navigation in a Hierarchy Viewer .... 29-7 29.4 Managing Nodes in a Hierarchy Viewer.............................................................................. 29-7 29.4.1 How to Specify Node Content ........................................................................................ 29-9 29.4.2 How to Configure the Controls on a Node................................................................. 29-10 29.4.3 Specifying a Node Definition for an Accessor............................................................ 29-11 29.4.4 Associating a Node Definition with a Particular Set of Data Rows ........................ 29-12 29.4.5 Specifying Ancestor Levels for an Anchor Node....................................................... 29-12 29.5 Adding Interactivity to a Hierarchy Viewer Component ................................................ 29-12 29.5.1 Configure a Hierarchy Viewer to Invoke a Popup Window.................................... 29-12 29.5.2 Configure a Hierarchy View Node to Invoke a Menu .............................................. 29-13 29.6 Using Panel Cards.................................................................................................................. 29-13 29.6.1 How to Create a Panel Card.......................................................................................... 29-13 29.6.2 What Happens at Runtime When a Panel Card Component Is Rendered ............ 29-14 29.7 Customizing the Appearance of a Hierarchy Viewer ...................................................... 29-14

xviii

29.7.1 29.7.2 29.7.3

How to Adjust the Size of a Hierarchy Viewer .......................................................... 29-14 How to Include Images in a Hierarchy Viewer.......................................................... 29-15 How to Configure the Display of the Control Panel ................................................. 29-15

Part V 30

Advanced Topics

Creating Custom ADF Faces Components30.1 Introduction to Custom ADF Faces Components ............................................................... 30-1 30.1.1 Developing a Custom Component with JDeveloper................................................... 30-2 30.1.2 An Example Custom Component .................................................................................. 30-5 30.2 Setting Up the Workspace and Starter Files......................................................................... 30-9 30.2.1 How to Set Up the JDeveloper Custom Component Environment ........................ 30-10 30.2.2 How to Add a Faces Configuration File...................................................................... 30-11 30.2.3 How to Add a MyFaces Trinidad Skins Configuration File..................................... 30-12 30.2.4 How to Add a Cascading Style Sheet .......................................................................... 30-13 30.2.5 How to Add a Resource Kit Loader ............................................................................ 30-13 30.2.6 How to Add a JavaServer Pages Tag Library Descriptor File ................................. 30-13 30.2.7 How to Add a JavaScript Library Feature Configuration File ................................. 30-14 30.3 Client-Side Development...................................................................................................... 30-14 30.3.1 How to Create a JavaScript File for a Component..................................................... 30-15 30.3.2 How to Create a Javascript File for an Event.............................................................. 30-16 30.3.3 How to Create a JavaScript File for a Peer .................................................................. 30-18 30.3.4 How to Add a Custom Component to a JavaScript Library Feature Configuration File . 30-19 30.4 Server-Side Development ..................................................................................................... 30-20 30.4.1 How to Create a Class for an Event Listener .............................................................. 30-20 30.4.2 How to Create a Class for an Event ............................................................................. 30-21 30.4.3 Creating the Component ............................................................................................... 30-22 30.4.4 How to Create a Class for a Component..................................................................... 30-24 30.4.5 How to Add the Component to the faces-config.xml File ........................................ 30-27 30.4.6 How to Create a Class for a Resource Bundle ............................................................ 30-27 30.4.7 How to Create a Class for a Renderer.......................................................................... 30-29 30.4.8 How to Add the Renderer to the faces-config.xml File............................................. 30-30 30.4.9 How to Create JSP Tag Properties................................................................................ 30-30 30.4.10 How to Configure the Tag Library Descriptor........................................................... 30-33 30.4.11 How to Create a Resource Loader................................................................................ 30-35 30.4.12 How to Create a MyFaces Trinidad Cascading Style Sheet ..................................... 30-36 30.5 Deploying a Component Library......................................................................................... 30-38 30.6 Adding the Custom Component to an Application ......................................................... 30-38 30.6.1 How to Configure the Web Deployment Descriptor................................................. 30-38 30.6.2 How to Enable JavaScript Logging and Assertions................................................... 30-39 30.6.3 How to Add a Custom Component to JSF Pages....................................................... 30-40 30.6.4 What You May Need to Know About Using the tagPane Custom Component ... 30-40

31

Allowing User Customization on JSF Pages31.1 Introduction to User Customization ..................................................................................... 31-1

xix

31.2 Implementing Session Change Persistence.......................................................................... 31-3 31.2.1 How to Implement Session Change Persistence .......................................................... 31-4 31.2.2 What Happens When You Configure Your Application to Use Change Persistence ....... 31-4 31.2.3 What Happens at Runtime .............................................................................................. 31-4 31.2.4 What You May Need to Know About Using Change Persistence on Templates and Regions 31-4

32 Adding Drag and Drop Functionality32.1 32.2 32.3 32.3.1 32.3.2 32.3.3 32.4 32.4.1 32.4.2 32.5 32.5.1 Introduction to Drag and Drop Functionality ..................................................................... Adding Drag and Drop Functionality for Attributes ......................................................... Adding Drag and Drop Functionality for Objects .............................................................. How to Add Drag and Drop Functionality for a Single Object ................................. What Happens at Runtime .............................................................................................. What You May Need to Know About Using the ClientDropListener ...................... Adding Drag and Drop Functionality for Collections ....................................................... How to Add Drag and Drop Functionality for Collections........................................ What You May Need to Know About the dragDropEndListener........................... Adding Drag and Drop Functionality for Components .................................................. How to Add Drag and Drop Functionality for Components................................... 32-1 32-3 32-3 32-4 32-7 32-8 32-8 32-9 32-11 32-11 32-12

Part VI

Appendixes

A ADF Faces ConfigurationA.1 Introduction to Configuring ADF Faces................................................................................. A.2 Configuration in web.xml......................................................................................................... A.2.1 How to Configure for JSF and ADF Faces in web.xml.................................................. A.2.2 What You May Need to Know About Required Elements in web.xml ...................... A.2.3 What You May Need to Know About ADF Faces Context Parameters in web.xml. A.2.3.1 State Saving .................................................................................................................. A.2.3.2 Debugging .................................................................................................................... A.2.3.3 File Uploading.............................................................................................................. A.2.3.4 Resource Debug Mode................................................................................................ A.2.3.5 User Customization..................................................................................................... A.2.3.6 Assertions ........................................................................................