Web UI Developer’s Guide For Oracle Application Development Framework

User Manual:

Open the PDF directly: View PDF .
Page Count: 1140

Download
Open PDF In Browser	View PDF

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:
Contributors:

Poh Lee Tan and Odile Sullivan-Tarazi

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.

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
1

Getting Started with ADF Faces

Introduction to ADF Faces
1.1
1.2
1.3

About Oracle ADF Faces ........................................................................................................... 1-1
ADF Faces Framework............................................................................................................... 1-1
ADF Faces Components............................................................................................................. 1-4

2 ADF Faces Demo Application
2.1
2.2

3

About the ADF Faces Demonstration Application ................................................................ 2-1
Downloading and Installing the ADF Faces Demo Application ...................................... 2-10

Getting Started with ADF Faces and JDeveloper
3.1
3.2
3.2.1
3.2.2
3.3
3.3.1
3.3.2
3.4
3.4.1
3.4.2
3.4.3
3.4.4
3.4.5

About Developing Declaratively in JDeveloper..................................................................... 3-1
Creating an Application Workspace ........................................................................................ 3-2
How to Create an ADF Faces Application Workspace .................................................. 3-2
What Happens When You Create an Application Workspace ..................................... 3-3
Defining Page Flows................................................................................................................... 3-4
How to Define a Page Flow................................................................................................ 3-5
What Happens When You Use the Diagrammer to Create a Page Flow .................... 3-6
Creating a View Page ................................................................................................................. 3-6
How to Create JSF Pages .................................................................................................... 3-9
What Happens When You Create a JSF Page .................................................................. 3-9
What You May Need to Know About Updating Your Application to Use the Facelets
Engine 3-14
What You May Need to Know About Automatic Component Binding .................. 3-15
How to Add ADF Faces Components to JSF Pages..................................................... 3-19

iii

3.4.6
3.4.7
3.4.8
3.5
3.5.1
3.5.2
3.5.3
3.6
3.6.1
3.6.2
3.6.3
3.7
3.7.1

Part II
4

3-21
3-22
3-24
3-24
3-25
3-27
3-28
3-29
3-29
3-31
3-31
3-32
3-32

Understanding ADF Faces Architecture

Using ADF Faces Client-Side Architecture
4.1
4.2
4.2.1
4.3
4.3.1
4.3.2
4.3.3
4.4
4.4.1
4.4.2
4.5
4.5.1
4.6
4.6.1
4.6.2
4.6.3
4.6.4
4.7
4.7.1
4.7.2
4.8
4.8.1
4.8.2
4.9
4.9.1
4.9.2
4.9.3

iv

What Happens When You Add Components to a Page .............................................
How to Set Component Attributes.................................................................................
What Happens When You Use the Property Inspector ..............................................
Creating EL Expressions .........................................................................................................
How to Create an EL Expression....................................................................................
How to Use the EL Format Tags.....................................................................................
How to Use EL Expressions Within Managed Beans..................................................
Creating and Using Managed Beans.....................................................................................
How to Create a Managed Bean in JDeveloper............................................................
What Happens When You Use JDeveloper to Create a Managed Bean...................
What You May Need to Know About Component Bindings and Managed Beans
Viewing ADF Faces Javadoc ..................................................................................................
How to View ADF Faces Source Code and Javadoc ...................................................

About Using ADF Faces Architecture...................................................................................... 4-1
Listening for Client Events ........................................................................................................ 4-3
How to Listen for Client Events ........................................................................................ 4-3
Adding JavaScript to a Page...................................................................................................... 4-4
How to Use Inline JavaScript ............................................................................................. 4-4
How to Import JavaScript Libraries .................................................................................. 4-5
What You May Need to Know About Accessing Client Event Sources ...................... 4-6
Instantiating Client-Side Components..................................................................................... 4-6
How to Configure a Component to for a Client-Side Instance ..................................... 4-6
What Happens When You Set clientComponent to true ............................................... 4-7
Locating a Client Component on a Page ................................................................................. 4-7
What You May Need to Know About Finding Components in Naming Containers .......
4-8
Accessing Component Properties on the Client..................................................................... 4-9
How to Set Property Values on the Client .................................................................... 4-13
What You May Need to Know About Setting Properties on the Client ................... 4-14
How to Unsecure the disabled Property ....................................................................... 4-17
What Happens at Runtime: How Client Properties Are Set on the Client............... 4-18
Using Bonus Attributes for Client-Side Components ........................................................ 4-18
How to Create Bonus Attributes .................................................................................... 4-18
What You May Need to Know About Marshalling Bonus Attributes...................... 4-19
Understanding Rendering and Visibility ............................................................................. 4-19
How to Set Visibility Using JavaScript .......................................................................... 4-21
What You May Need to Know About Visible and the isShowing Function............ 4-22
JavaScript Library Partitioning .............................................................................................. 4-22
How to Create a JavaScript Feature ............................................................................... 4-23
How to Create JavaScript Partitions .............................................................................. 4-24
What Happens at Runtime: JavaScript Partitioning.................................................... 4-26

5 Using the JSF Lifecycle with ADF Faces
5.1
5.2
5.2.1
5.3
5.3.1
5.3.2
5.4
5.5
5.6
5.7
5.7.1
5.7.2
5.7.3

6

About Using the JSF Lifecycle and ADF Faces ....................................................................... 5-1
Using the Immediate Attribute ................................................................................................. 5-4
How to Use the Immediate Attribute ............................................................................... 5-9
Using the Optimized Lifecycle.................................................................................................. 5-9
What You May Need to Know About Using the Immediate Attribute and the
Optimized Lifecycle 5-10
What You May Need to Know About Using an LOV Component and the Optimized
Lifecycle 5-11
Using the Client-Side Lifecycle .............................................................................................. 5-14
Using Subforms to Create Sections on a Page ..................................................................... 5-15
Object Scope Lifecycles ........................................................................................................... 5-15
Passing Values Between Pages .............................................................................................. 5-17
How to Use the pageFlowScope Scope Within Java Code ......................................... 5-18
How to Use the pageFlowScope Scope Without Writing Java Code ........................ 5-19
What Happens at Runtime: How Values are Passed .................................................. 5-20

Handling Events
6.1
6.1.1
6.1.2
6.2
6.2.1
6.3
6.3.1
6.3.2
6.3.3
6.3.4
6.3.5
6.3.6
6.3.7
6.3.8
6.4
6.4.1
6.4.2
6.4.3
6.5
6.6
6.6.1
6.7
6.7.1

About Events and Event Handling .......................................................................................... 6-1
Events and Partial Page Rendering................................................................................... 6-2
Client-Side Event Model..................................................................................................... 6-3
Using ADF Faces Server Events................................................................................................ 6-3
How to Handle Server-Side Events .................................................................................. 6-5
Using JavaScript for ADF Faces Client Events ....................................................................... 6-6
How to Use Client-Side Events....................................................................................... 6-10
How to Return the Original Source of the Event ......................................................... 6-12
How to Use Client-Side Attributes for an Event.......................................................... 6-13
How to Block UI Input During Event Execution ......................................................... 6-13
How to Prevent Events from Propagating to the Server ............................................ 6-14
How to Indicate No Response is Expected ................................................................... 6-14
What Happens at Runtime: How Client-Side Events Work ...................................... 6-15
What You May Need to Know About Using Naming Containers............................ 6-15
Sending Custom Events from the Client to the Server....................................................... 6-16
How to Send Custom Events from the Client to the Server ....................................... 6-17
What Happens at Runtime: How Client and Server Listeners Work Together ...... 6-18
What You May Need to Know About Marshalling and Unmarshalling Data ........ 6-19
Executing a Script Within an Event Response..................................................................... 6-21
Using ADF Faces Client Behavior Tags ................................................................................ 6-22
How to Use the scrollComponentIntoViewBehavior Tag .......................................... 6-23
Using Polling Events to Update Pages ................................................................................. 6-24
How to Use the Poll Component.................................................................................... 6-25

7 Validating and Converting Input
7.1
7.1.1
7.1.2

About ADF Faces Converters and Validators ........................................................................ 7-1
ADF Faces Converters and Validators Use Cases and Examples................................. 7-2
Additional Functionality for ADF Faces Converters and Validators .......................... 7-2

v

7.2
7.3
7.3.1
7.3.2
7.3.3
7.4
7.4.1
7.4.2
7.5
7.5.1
7.5.1.1
7.5.1.2
7.5.1.3
7.5.2
7.5.3
7.6
7.6.1
7.6.2
7.6.3
7.6.4

Conversion, Validation, and the JSF Lifecycle........................................................................ 7-2
Adding Conversion .................................................................................................................... 7-3
How to Add a Converter .................................................................................................... 7-4
How to Set Attributes on a Converter .............................................................................. 7-5
What Happens at Runtime ................................................................................................. 7-6
Creating Custom JSF Converters .............................................................................................. 7-6
How to Create a Custom JSF Converter........................................................................... 7-6
What Happens When You Use a Custom Converter .................................................. 7-10
Adding Validation ................................................................................................................... 7-10
How to Add Validation ................................................................................................... 7-11
Adding ADF Faces Validation................................................................................. 7-11
Using Validation Attributes ..................................................................................... 7-11
Using ADF Faces Validators .................................................................................... 7-12
What Happens at Runtime .............................................................................................. 7-13
What You May Need to Know About Multiple Validators........................................ 7-13
Creating Custom JSF Validation............................................................................................ 7-14
How to Create a Backing Bean Validation Method ..................................................... 7-14
What Happens When You Create a Backing Bean Validation Method.................... 7-15
How to Create a Custom JSF Validator ......................................................................... 7-15
What Happens When You Use a Custom JSF Validator............................................. 7-17

8 Rerendering Partial Page Content
8.1
8.2
8.2.1
8.2.2
8.2.3
8.3
8.3.1
8.4
8.4.1
8.4.2

Part III

About 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 .............................................................
How to Enable Partial Page Rendering Programmatically ...........................................
Using Partial Page Navigation..................................................................................................
How to Use Partial Page Navigation ................................................................................
What You May Need to Know About PPR Navigation.................................................

8-1
8-2
8-4
8-6
8-6
8-6
8-6
8-7
8-8
8-8

Creating Your Layout

9 Organizing Content on Web Pages
9.1
9.1.1
9.2
9.2.1
9.2.2
9.2.3
9.2.4
9.2.5
9.3
9.3.1

vi

About Organizing Content on Web Pages .............................................................................. 9-1
Additional Functionality for Layout Components ......................................................... 9-4
Starting to Lay Out a Page......................................................................................................... 9-5
Geometry Management and Component Stretching ..................................................... 9-6
Nesting Components Inside Components That Allow Stretching ............................... 9-8
Using Quick Start Layouts .............................................................................................. 9-10
Tips for Using Geometry-Managed Components ....................................................... 9-11
How to Configure the document Tag............................................................................ 9-12
Arranging Contents to Stretch Across a Page...................................................................... 9-15
How to Use the panelStretchLayout Component ........................................................ 9-16

9.3.2
9.4
9.4.1
9.4.2
9.5
9.5.1
9.6
9.6.1
9.6.2
9.7
9.7.1
9.7.2
9.8
9.8.1
9.8.2
9.8.3
9.8.4
9.9
9.9.1
9.9.2
9.9.3
9.9.4
9.9.5
9.10
9.10.1
9.10.2
9.10.3
9.11
9.11.1
9.11.2
9.12
9.12.1
9.12.2
9.13
9.13.1
9.13.2

What You May Need to Know About Geometry Management and the
panelStretchLayout Component 9-19
Using Splitters to Create Resizable Panes ............................................................................ 9-20
How to Use the panelSplitter Component .................................................................... 9-21
What You May Need to Know About Geometry Management and the panelSplitter
Component 9-25
Arranging Page Contents in Predefined Fixed Areas ........................................................ 9-26
How to Use the panelBorderLayout Component to Arrange Page Contents in
Predefined Fixed Areas 9-27
Arranging Content in Forms .................................................................................................. 9-28
How to Use the panelFormLayout Component........................................................... 9-30
What You May Need to Know About Using the group Component with the
panelFormLayout Component 9-34
Arranging Contents in a Dashboard ..................................................................................... 9-38
How to Use the panelDashboard Component ............................................................. 9-41
What You May Need to Know About Geometry Management and the panelDashboard
Component 9-44
Displaying and Hiding Contents Dynamically ................................................................... 9-44
How to Use the showDetail Component ...................................................................... 9-49
How to Use the showDetailHeader Component ......................................................... 9-50
How to Use the panelBox Component .......................................................................... 9-53
What You May Need to Know About Disclosure Events........................................... 9-54
Displaying or Hiding Contents in Accordion Panels and Tabbed Panels....................... 9-56
How to Use the panelAccordion Component .............................................................. 9-60
How to Use the panelTabbed Component.................................................................... 9-62
How to Use the showDetailItem Component to Display Content in panelAccordion or
panelTabbed Components 9-63
What You May Need to Know About Geometry Management and the showDetailItem
Component 9-67
What You May Need to Know About showDetailItem Disclosure Events ............. 9-68
Displaying Items in a Static Box ............................................................................................ 9-69
How to Use the panelHeader Component.................................................................... 9-72
How to Use the decorativeBox Component ................................................................. 9-74
What You May Need to Know About Geometry Management and the decorativeBox
Component 9-75
Displaying a Bulleted List in One or More Columns ......................................................... 9-76
How to Use the panelList Component .......................................................................... 9-77
What You May Need to Know About Creating a List Hierarchy ............................. 9-78
Grouping Related Items .......................................................................................................... 9-79
How to Use the panelGroupLayout Component......................................................... 9-81
What You May Need to Know About Geometry Management and the
panelGroupLayout Component 9-83
Separating Content Using Blank Space or Lines ................................................................. 9-83
How to Use the spacer Component ............................................................................... 9-84
How to Use the Separator Component.......................................................................... 9-85

10 Creating and Reusing Fragments, Page Templates, and Components
10.1

About Reusable Content ......................................................................................................... 10-1

vii

10.1.1
Reusable Components Use Cases and Examples.........................................................
10.1.2
Additional Functionality for Reusable Components...................................................
10.2
Common Functionality in Reusable Components ..............................................................
10.2.1
Page in Request Scope......................................................................................................
10.2.2
Access to Child Components for Customization .........................................................
10.3
Using Page Fragments.............................................................................................................
10.3.1
How to Create a Page Fragment.....................................................................................
10.3.2
What Happens When You Create a Page Fragment....................................................
10.3.3
How to Use a Page Fragment in a JSF Page..................................................................
10.3.3.1
Adding a Page Fragment Using the Component Palette.....................................
10.3.3.2
Adding a Page Fragment Using the Application Navigator...............................
10.3.4
What Happens at Runtime: Resolving Page Fragments ...........................................
10.4
Using Page Templates ...........................................................................................................
10.4.1
How to Create a Page Template ...................................................................................
10.4.2
What Happens When You Create a Page Template ..................................................
10.4.3
How to Create JSF Pages Based on Page Templates..................................................
10.4.4
What Happens When You Use a Template to Create a Page...................................
10.4.5
What Happens at Runtime: How Page Templates Are Resolved ...........................
10.4.6
What You May Need to Know About Page Templates and Naming Containers.
10.5
Using Declarative Components ...........................................................................................
10.5.1
How to Create a Declarative Component ...................................................................
10.5.2
What Happens When You Create a Declarative Component ..................................
10.5.3
How to Deploy Declarative Components ...................................................................
10.5.4
How to Use Declarative Components in JSF Pages ...................................................
10.5.5
What Happens When You Use a Declarative Component on a JSF Page ..............
10.5.6
What Happens at Runtime ............................................................................................
10.6
Adding Resources to Pages ..................................................................................................
10.6.1
How to Add Resources to Page Templates and Declarative Components ............
10.6.2
What Happens at Runtime: Adding Resources to the Document Header.............

Part IV
11

Using Common ADF Faces Components

Using Input Components and Defining Forms
11.1
11.1.1
11.1.2
11.2
11.2.1
11.2.2
11.2.3
11.3
11.3.1
11.3.2
11.4
11.4.1
11.4.2
11.5

viii

10-3
10-4
10-4
10-4
10-4
10-4
10-7
10-8
10-9
10-9
10-9
10-10
10-10
10-14
10-18
10-18
10-20
10-21
10-22
10-22
10-25
10-29
10-31
10-31
10-33
10-34
10-34
10-35
10-35

About Input Components and Forms...................................................................................
Input Component Use Cases and Examples.................................................................
Additional Functionality for Input Components and Forms.....................................
Defining Forms.........................................................................................................................
How to Add a Form to a Page ........................................................................................
How to Add a Subform to a Page...................................................................................
How to Add a Reset Button to a Form ..........................................................................
Using the inputText Component ...........................................................................................
How to Add an inputText Component .......................................................................
How to Add the Ability to Insert Text into an inputText Component ...................
Using the Input Number Components ...............................................................................
How to Add an inputNumberSlider or an inputRangeSlider Component ...........
How to Add an inputNumberSpinbox Component..................................................
Using Color and Date Choosers ..........................................................................................

11-1
11-3
11-5
11-6
11-7
11-8
11-8
11-9
11-10
11-13
11-14
11-15
11-16
11-17

11.5.1
11.5.2
11.5.3
11.6
11.6.1
11.6.2
11.7
11.7.1
11.7.2
11.8
11.8.1
11.8.2
11.8.3
11.9
11.9.1
11.9.2

How to Add an inputColor Component ..................................................................... 11-18
How to Add an InputDate Component ...................................................................... 11-20
What You May Need to Know About Selecting Time Zones Without the inputDate
Component 11-21
Using Selection Components ............................................................................................... 11-22
How to Use Selection Components.............................................................................. 11-26
What You May Need to Know About the contentDelivery Attribute on the
SelectManyChoice Component 11-29
Using Shuttle Components................................................................................................... 11-30
How to Add a selectManyShuttle or selectOrderShuttle Component.................... 11-31
What You May Need to Know About Using a Client Listener for Selection Events ........
11-33
Using the richTextEditor Component................................................................................. 11-34
How to Add a richTextEditor Component ................................................................. 11-36
How to Add the Ability to Insert Text into a richTextEditor Component ............. 11-37
How to Customize the Toolbar..................................................................................... 11-38
Using File Upload .................................................................................................................. 11-40
How to Use the inputFile Component......................................................................... 11-43
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

ix

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
13.1.1
13.2
13.2.1
13.3
13.3.1
13.4
13.4.1

About List-of-Values Components........................................................................................
Additional Functionality for List-of-Values Components..........................................
Creating the ListOfValues Data Model.................................................................................
How to Create the ListOfValues Data Model...............................................................
Using the inputListOfValues Component..........................................................................
How to Use the InputListOfValues Component........................................................
Using the InputComboboxListOfValues Component ......................................................
How to Use the InputComboboxListOfValues Component ....................................

13-1
13-7
13-8
13-9
13-10
13-10
13-12
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

x

15 Using Popup Dialogs, Menus, and Windows
About Popup Dialogs, Menus, and Windows..................................................................... 15-1
Popup Dialogs, Menus, Windows Use Cases and Examples..................................... 15-3
Additional Functionality for Popup Dialogs, Menus, and Windows....................... 15-4
Declaratively Creating Popups .............................................................................................. 15-4
How to Create a Dialog.................................................................................................... 15-7
How to Create a Panel Window ................................................................................... 15-11
How to Create a Context Menu .................................................................................... 15-13
How to Create a Note Window .................................................................................... 15-14
What Happens at Runtime: Popup Component Events ........................................... 15-16
What You May Need to Know About Dialog Events................................................ 15-18
Declaratively Invoking a Popup .......................................................................................... 15-19
How to Declaratively Invoke a Popup Using the af:showPopupBehavior Tag .... 15-19
What Happens When You Use af:showPopupBehavior Tag to Invoke a Popup . 15-20
Programmatically Invoking a Popup.................................................................................. 15-21
How to Programmatically Invoke a Popup ................................................................ 15-22
What Happens When You Programmatically Invoke a Popup............................... 15-23
Displaying Contextual Information in Popups ................................................................. 15-23
How to Create Contextual Information....................................................................... 15-24
Controlling the Automatic Cancellation of Inline Popups .............................................. 15-25
How to Disable the Automatic Cancellation of an Inline Popup ............................ 15-26
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

15.1
15.1.1
15.1.2
15.2
15.2.1
15.2.2
15.2.3
15.2.4
15.2.5
15.2.6
15.3
15.3.1
15.3.2
15.4
15.4.1
15.4.2
15.5
15.5.1
15.6
15.6.1
15.6.2

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.1
Calendar Use Cases and Examples ................................................................................
17.1.2
Additional Functionality for the Calendar ...................................................................
17.2
Creating the Calendar .............................................................................................................
17.2.1
Calendar Classes ...............................................................................................................
17.2.2
How to Create a Calendar ...............................................................................................

17-1
17-4
17-4
17-5
17-6
17-6

xi

17.3
17.3.1
17.3.2
17.4
17.4.1
17.5
17.5.1
17.6
17.6.1
17.6.2
17.6.3

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 ............................................
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...............................................................................................

17-7
17-7
17-10
17-11
17-12
17-14
17-14
17-16
17-17
17-19
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

xii

19.4
Grouping Components with a Single Label and Message...............................................
19.4.1
How to Group Components with a Single Label and Message...............................
19.5
Displaying Help for Components .......................................................................................
19.5.1
How to Create Resource Bundle-Based Help.............................................................
19.5.2
How to Create XLIFF-Based Help................................................................................
19.5.3
How to Create Managed Bean Help ............................................................................
19.5.4
How to Use JavaScript to Launch an External Help Window .................................
19.5.5
How to Create a Java Class Help Provider .................................................................
19.5.6
How to Access Help Content from a UI Component................................................
19.5.7
What You May Need to Know About Combining Different Message Types .......

19-15
19-16
19-17
19-20
19-22
19-24
19-27
19-28
19-29
19-30

20 Working with Navigation Components
20.1
20.1.1
20.1.2
20.2
20.3
20.3.1
20.3.2
20.3.3
20.4
20.4.1
20.4.2
20.5
20.5.1
20.5.2
20.6
20.6.1
20.7
20.7.1
20.7.2
20.7.3
20.7.4
20.7.5
20.7.6
20.7.7
20.8
20.8.1
20.8.2
20.8.3
20.9
20.9.1
20.9.2
20.9.3

Part V

About Navigation Components............................................................................................. 20-1
Navigation Components Use Cases and Examples..................................................... 20-2
Additional Functionality for Navigation Components............................................... 20-5
Common Functionality in Navigation Components .......................................................... 20-6
Using Buttons and Links for Navigation.............................................................................. 20-6
How to Use Command Buttons and Command Links ............................................... 20-8
How to Use Go Buttons and Go Links ........................................................................ 20-10
What You May Need to Know About Using Partial Page Navigation................... 20-11
Configuring a Browser’s Context Menu for Command Links ........................................ 20-12
How to Configure a Browser’s Context Menu for Command Links ...................... 20-12
What Happens When You Configure a Browser’s Context Menu for Command Links ..
20-13
Using Buttons or Links to Invoke Functionality ............................................................... 20-13
How to Use a Command Component to Download Files ........................................ 20-14
How to Use a Command Component to Reset Input Fields .................................... 20-16
Using Navigation Items for a Page Hierarchy................................................................... 20-17
How to Create Navigation Cases for a Page Hierarchy............................................ 20-20
Using a Menu Model to Create a Page Hierarchy............................................................. 20-22
How to Create the Menu Model Metadata ................................................................. 20-23
What Happens When You Use the Create ADF Menu Model Wizard .................. 20-30
How to Bind the navigationPane Component to the Menu Model ........................ 20-32
How to Use the breadCrumbs Component with a Menu Model ............................ 20-36
How to Use the menuBar Component with a Menu Model .................................... 20-37
What Happens at Runtime ............................................................................................ 20-39
What You May Need to Know About Using Custom Attributes............................ 20-41
Creating a Simple Navigational Hierarchy........................................................................ 20-43
How to Create a Simple Page Hierarchy..................................................................... 20-44
How to Use the breadCrumbs Component ................................................................ 20-48
What You May Need to Know About Removing Navigation Tabs........................ 20-50
Using Train Components to Create Navigation Items for a Multistep Process ........... 20-51
How to Create the Train Model.................................................................................... 20-54
How to Configure Managed Beans for the Train Model .......................................... 20-57
How to Bind to the Train Model in JSF Pages ............................................................ 20-61

Using ADF Data Visualization Components
xiii

21 Introduction to ADF Data Visualization Components
21.1
About ADF Data Visualization Components ......................................................................
21.1.1
Graph Component Use Cases and Examples ...............................................................
21.1.2
Gauge Component Use Cases and Examples...............................................................
21.1.3
Pivot Table Use Cases and Examples ............................................................................
21.1.4
Geographic Map Use Cases and Examples...................................................................
21.1.5
Thematic Map Component Use Cases and Examples.................................................
21.1.6
Gantt Chart Component Use Cases and Examples .....................................................
21.1.7
Hierarchy Viewer Component Use Cases and Examples...........................................
21.1.8
Additional Functionality for Data Visualization Components................................
21.2
Common Functionality in Data Visualization Components ...........................................
21.2.1
Content Delivery.............................................................................................................
21.2.2
Automatic Partial Page Rendering (PPR)....................................................................
21.2.3
Image Formats for Graph and Gauge Components ..................................................
21.2.4
Embedded Fonts for Graph and Gauge Components...............................................
21.2.5
Graph and Gauge Context Menus ...............................................................................
21.2.6
Screen Reader Support ..................................................................................................
21.2.7
Text Resources from Application Resource Bundles ................................................
21.3
Providing Data for ADF Data Visualization Components ..............................................

21-1
21-1
21-4
21-6
21-6
21-7
21-8
21-9
21-10
21-11
21-11
21-12
21-13
21-13
21-14
21-15
21-15
21-16

22 Using Graph Components
22.1
About the Graph Component ................................................................................................
22.1.1
End User and Presentation Features..............................................................................
22.1.1.1
Graph Layout .............................................................................................................
22.1.1.2
Sizing ...........................................................................................................................
22.1.1.3
Data Marker Selection...............................................................................................
22.1.1.4
Context Menus ...........................................................................................................
22.1.1.5
Reference Areas/Line and Alerts............................................................................
22.1.1.6
Hide and Show Series ...............................................................................................
22.1.1.7
Drilling ........................................................................................................................
22.1.1.8
Annotations ................................................................................................................
22.1.1.9
Popup Support...........................................................................................................
22.1.1.10
Time Selector ..............................................................................................................
22.1.1.11
Bi-directional Support...............................................................................................
22.1.1.12
Drag and Drop ...........................................................................................................
22.1.1.13
Screen Reader Support..............................................................................................
22.1.2
Graph Component Use Cases and Examples ...............................................................
22.1.3
Additional Functionality for Graph Components .....................................................
22.2
Using the Graph Component ...............................................................................................
22.2.1
Graph Type Data Requirements...................................................................................
22.2.2
Configuring Graphs .......................................................................................................
22.2.3
How to Add a Graph to a Page.....................................................................................
22.2.4
What Happens When You Add a Graph to a Page ...................................................
22.2.5
How to Create a Graph Using Tabular Data .............................................................
22.2.6
What You May Need to Know About Flash and PNG Image Formats..................
22.2.7
Editing Graphs in the Visual Editor and Property Inspector...................................
22.3
Customizing Graph Display Elements ...............................................................................
xiv

22-1
22-2
22-2
22-2
22-2
22-2
22-3
22-3
22-4
22-4
22-5
22-5
22-6
22-6
22-6
22-7
22-16
22-17
22-17
22-21
22-26
22-28
22-29
22-30
22-31
22-32

22.3.1
Changing Graph Size and Style ...................................................................................
22.3.1.1
How to Specify the Size of a Graph at Initial Display........................................
22.3.1.2
How to Provide for Dynamic Resizing of a Graph ............................................
22.3.1.3
How to Use a Specific Style Sheet for a Graph....................................................
22.3.2
Changing Graph Background, Plot Area, and Title ..................................................
22.3.2.1
How to Customize the Background and Plot Area of a Graph ........................
22.3.2.2
How to Specify Titles and Footnotes in a Graph ................................................
22.3.3
How to Customize Graph Axes and Labels................................................................
22.3.3.1
How to Specify the Title, Appearance, and Scaling of an Axis ........................
22.3.3.2
How to Specify Scrolling on an Axis ....................................................................
22.3.3.3
How to Control the Appearance of Tick Marks and Labels on an Axis..........
22.3.3.4
How to Format Numbers on an Axis ...................................................................
22.3.3.5
How to Set Minimum and Maximum Values on a Data Axis ..........................
22.3.4
Customizing Graph Legends ........................................................................................
22.3.5
Customizing Tooltips in Graphs ..................................................................................
22.4
Formatting Graph Text, Colors, and Data Values.............................................................
22.4.1
Formatting Text in Graphs ............................................................................................
22.4.1.1
How to Globally Set Graph Font Using a Skin ...................................................
22.4.2
Specifying Transparent Colors for Parts of a Graph .................................................
22.4.3
Using Gradient Special Effects in Graphs ...................................................................
22.4.3.1
How to Add Gradient Special Effects to a Graph...............................................
22.4.3.2
What Happens When You Add a Gradient Special Effect to a Graph ............
22.4.4
Formatting Data Values in Graphs ..............................................................................
22.4.4.1
How to Format Categorical Data Values .............................................................
22.4.4.2
How to Format Numerical Data Values...............................................................
22.4.4.3
What You May Need to Know About Automatic Scaling and Precision........
22.5
Customizing the Appearance of Series and Groups of Data...........................................
22.5.1
Changing the Color, Style, and Display of Graph Data Values...............................
22.5.1.1
How to Specify the Color and Style for Individual Series Items......................
22.5.1.2
How to Control the Number of Different Colors Used for Series Items .........
22.5.1.3
How to Enable Hiding and Showing Series Items .............................................
22.5.2
Changing the Appearance of Pie Graphs....................................................................
22.5.2.1
How to Customize the Overall Appearance of Pie Graphs ..............................
22.5.2.2
How to Customize an Exploding Pie Slice ..........................................................
22.5.3
Changing the Appearance of Lines in Graphs ...........................................................
22.5.3.1
How to Display Either Data Lines or Markers in Graphs .................................
22.5.3.2
How to Change the Appearance of Lines in a Graph Series.............................
22.5.4
Customizing Pareto Graphs ..........................................................................................
22.5.5
Customizing Scatter Graph Series Marker Data Values ...........................................
22.5.6
Customizing Graph Marker Shapes.............................................................................
22.5.7
Adding Reference Lines or Areas to Graphs ..............................................................
22.5.7.1
How to Create Reference Lines or Areas During Design ..................................
22.5.7.2
What Happens When You Create Reference Lines or Areas During Design.
22.5.7.3
How to Create Reference Lines or Areas Dynamically......................................
22.6
Animating Graphs .................................................................................................................
22.6.1
How to Configure Graph Components to Display Active Data..............................
22.6.2
How to Specify Animation Effects for Graphs ...........................................................

22-32
22-33
22-33
22-33
22-34
22-34
22-35
22-35
22-36
22-37
22-37
22-38
22-39
22-39
22-40
22-41
22-41
22-42
22-44
22-44
22-45
22-46
22-46
22-46
22-47
22-49
22-49
22-49
22-50
22-50
22-51
22-51
22-51
22-51
22-52
22-52
22-53
22-53
22-53
22-54
22-56
22-56
22-57
22-58
22-58
22-59
22-59

xv

22.7
Adding Interactive Features to Graphs ..............................................................................
22.7.1
Providing Interactive Capability for Graphs ..............................................................
22.7.1.1
How to Provide Marker and Legend Dimming..................................................
22.7.1.2
How to React to Changes in the Zoom and Scroll Levels..................................
22.7.2
Providing an Interactive Time Axis for Graphs .........................................................
22.7.2.1
How to Define a Relative Range of Time Data for Display...............................
22.7.2.2
How to Define an Explicit Range of Time Data for Display .............................
22.7.3
Adding Alerts and Annotations to Graphs.................................................................
22.7.4
Creating Drillable Graphs .............................................................................................
22.7.5
How to Add Drag and Drop to Graphs ......................................................................
22.7.6
How to Add Popups to Graphs....................................................................................
22.7.7
How to Configure Graph Context Menus...................................................................

22-60
22-61
22-61
22-61
22-62
22-62
22-62
22-63
22-64
22-65
22-67
22-69

23 Using Gauge Components
23.1
23.1.1
23.1.2
23.1.3
23.2
23.2.1
23.2.2
23.2.3
23.2.4
23.2.5
23.2.6
23.3
23.3.1
23.3.2
23.3.3
23.3.4
23.3.5
23.4
23.4.1
23.4.2
23.4.3
23.5
23.5.1
23.5.2
23.6
23.6.1
23.6.2
23.6.3
23.6.4
23.6.5
23.6.6
23.7
23.7.1

xvi

About the Gauge Component ................................................................................................
End User and Presentation Features of Gauge Components .....................................
Gauge Component Use Cases and Examples...............................................................
Additional Functionality of Gauge Components.........................................................
Using the Gauge Component.................................................................................................
Configuring Gauges .........................................................................................................
How to Add a Gauge to a Page ......................................................................................
What Happens When You Add a Gauge to a Page ...................................................
How to Create a Gauge Using Tabular Data .............................................................
What You May Need to Know About Flash and PNG Image Formats..................
Using Gauges in Tables..................................................................................................
Configuring Gauge Display Elements ................................................................................
How to Configure Gauge Thresholds..........................................................................
How to Customize Gauge Labels.................................................................................
How to Customize Gauge Indicators and Tick Marks..............................................
How to Specify the Layout of Gauges in a Gauge Set...............................................
What You May Need to Know About Configuring Gauge Set Display.................
Formatting Gauge Style Elements .......................................................................................
How to Change Gauge Size and Apply CSS Styles ...................................................
Specifying Transparency for Gauge Elements ...........................................................
How to Format Gauge Text and Use Text Resources................................................
Formatting Numeric Data Values in Gauges.....................................................................
How to Format Numeric Data Values in Gauges ......................................................
What You May Need to Know About Automatic Scaling and Precision...............
Adding Gauge Special Effects and Animation ..................................................................
How to Add Gradient Special Effects to a Gauge......................................................
What Happens When You Add a Gradient Special Effect to a Gauge ...................
How to Add Interactivity to Gauges ...........................................................................
Animating Gauges..........................................................................................................
How to Specify Animation Effects for Gauges...........................................................
How to Configure Gauges to Display Active Data ...................................................
Using Custom Shapes for Gauges .......................................................................................
How to Use Prebuilt Custom Shapes Styles ...............................................................

23-1
23-1
23-2
23-5
23-5
23-6
23-7
23-10
23-11
23-13
23-14
23-15
23-15
23-16
23-17
23-20
23-21
23-21
23-21
23-22
23-22
23-24
23-24
23-25
23-25
23-25
23-27
23-27
23-29
23-30
23-30
23-31
23-31

23.7.2
23.7.3

How to Use a Custom Shapes Graphic File ................................................................ 23-32
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.1
End User and Presentation Features of Pivot Table Components ............................
24.1.1.1
Pivot Filter Bar ...........................................................................................................
24.1.1.2
Pivoting .......................................................................................................................
24.1.1.3
Editing Data Cells......................................................................................................
24.1.1.4
Sorting .........................................................................................................................
24.1.1.5
Drilling ........................................................................................................................
24.1.1.6
On Demand Data Scrolling ......................................................................................
24.1.1.7
Sizing ...........................................................................................................................
24.1.2
Pivot Table and Pivot Filter Bar Component Use Cases and Examples...................
24.1.3
Additional Functionality for the Pivot Table Component..........................................
24.2
Using the Pivot Table Component ......................................................................................
24.2.1
Configuring Pivot Tables...............................................................................................
24.2.2
How to Add a Pivot Table to a Page............................................................................
24.2.3
What Happens When You Add a Pivot Table to a Page...........................................
24.3
Using Stamping in Pivot Tables...........................................................................................
24.3.1
How to Configure Header and Data Cells as Stamps ...............................................
24.3.2
What You May Need to Know About Using var and varStatus Properties ..........
24.4
Using a Pivot Filter Bar with a Pivot Table ........................................................................
24.4.1
How to Associate a Pivot Filter Bar with a Pivot Table ............................................
24.5
Customizing Pivot Table Cell Content ...............................................................................
24.5.1
How to Create a CellFormat Object for a Data Cell...................................................
24.5.2
How to Change Cell Format .........................................................................................
24.5.3
How to Create Stoplight and Conditional Formatting in a Pivot Table ................
24.6
Using Selection in Pivot Tables............................................................................................
24.7
Updating Pivot Tables with Partial Page Rendering........................................................
24.8
How to Export from a Pivot Table ......................................................................................

25

24-1
24-1
24-2
24-2
24-3
24-4
24-4
24-5
24-5
24-6
24-9
24-10
24-10
24-12
24-14
24-14
24-15
24-19
24-22
24-23
24-24
24-24
24-25
24-27
24-28
24-28
24-29

Using Map Components
25.1
About Map Components ........................................................................................................
25.1.1
End User and Presentation Features of Maps ..............................................................
25.1.1.1
Geographic Map End User and Presentation Features........................................
25.1.1.2
Thematic Map End User and Presentation Features ............................................
25.1.2
Map Component Use Cases and Examples ..................................................................
25.1.3
Additional Functionality for Map Components ..........................................................
25.2
Using the Geographic Map Component.............................................................................
25.2.1
Configuring Geographic Map Components ...............................................................
25.2.2
How to Add a Geographic Map to a Page ..................................................................
25.2.3
What Happens When You Add a Geographic Map to a Page.................................
25.3
Customizing Geographic Map Display Attributes ...........................................................
25.3.1
How to Adjust the Map Size .........................................................................................
25.3.2
How to Specify Strategy for Map Zoom Control .......................................................

25-1
25-1
25-2
25-5
25-7
25-9
25-10
25-11
25-12
25-15
25-16
25-16
25-16

xvii

25.3.3
25.3.4
25.4
25.4.1
25.4.2
25.4.3
25.4.4
25.4.5
25.4.6
25.4.7
25.4.8
25.4.9
25.5
25.5.1
25.5.2
25.6
25.6.1
25.6.2
25.6.3
25.6.4
25.6.5
25.6.6
25.7
25.7.1
25.7.2
25.7.3
25.8
25.8.1
25.8.2
25.8.3
25.8.4

How to Customize and Use Map Selections...............................................................
How to Customize the Map Legend............................................................................
Customizing Geographic Map Themes ..............................................................................
How to Customize Zoom Levels for a Theme............................................................
How to Customize the Labels of a Map Theme .........................................................
How to Customize Color Map Themes .......................................................................
How to Customize Point Images in a Point Theme...................................................
What Happens When You Customize the Point Images in a Map .........................
How to Customize the Bars in a Bar Graph Theme...................................................
What Happens When You Customize the Bars in a Map Bar Graph Theme ........
How to Customize the Slices in a Pie Graph Theme .................................................
What Happens When You Customize the Slices in a Map Pie Graph Theme.......
Adding a Toolbar to a Geographic Map.............................................................................
How to Add a Toolbar to a Map ..................................................................................
What Happens When You Add a Toolbar to a Map .................................................
Using Thematic Map Components......................................................................................
Configuring Thematic Maps .........................................................................................
What You May Need to Know About Prebuilt Base Maps ......................................
Using the Layer Browser ...............................................................................................
How to Add a Thematic Map to a Page ......................................................................
What Happens When You Add a Thematic Map to a Page .....................................
What You May Need to Know About Flash and PNG Image Formats..................
Customizing Thematic Map Display Attributes ...............................................................
How to Customize Thematic Map Labels...................................................................
How to Configure Tooltips to Display Data...............................................................
How to Format Numeric Data Values in Area and Marker Labels.........................
Adding Interactivity to Thematic Maps .............................................................................
How to Configure Selection and Action Events in Thematic Maps........................
How to Add Popups to Thematic Map Areas and Markers ....................................
How to Configure Animation Effects ..........................................................................
How to Add Drag and Drop to Thematic Map Components ..................................

25-17
25-19
25-21
25-21
25-21
25-22
25-23
25-24
25-24
25-25
25-25
25-26
25-27
25-27
25-28
25-28
25-28
25-33
25-33
25-34
25-38
25-38
25-39
25-39
25-41
25-41
25-42
25-42
25-44
25-48
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

xviii

26.2.1
Data for a Project Gantt Chart.........................................................................................
26.2.2
Data for a Resource Utilization Gantt Chart.................................................................
26.2.3
Data for a Scheduling Gantt Chart...............................................................................
26.2.4
Gantt Chart Tasks ...........................................................................................................
26.2.5
Configuring Gantt Charts..............................................................................................
26.2.6
How to Add a Gantt Chart to a Page...........................................................................
26.2.7
What Happens When You Add a Gantt Chart to a Page..........................................
26.3
Customizing Gantt Chart Legends, Toolbars, and Context Menus ...............................
26.3.1
How to Customize a Gantt Chart Legend...................................................................
26.3.2
Customizing Gantt Chart Toolbars ..............................................................................
26.3.3
Customizing Gantt Chart Context Menus ..................................................................
26.4
Working with Gantt Chart Tasks and Resources ..............................................................
26.4.1
How to Create a New Task Type .................................................................................
26.4.2
How to Specify Custom Data Filters............................................................................
26.4.3
How to Add a Double-Click Event to a Task Bar ......................................................
26.5
Specifying Nonworking Days, Read-Only Features, and Time Axes ............................
26.5.1
Identifying Nonworking Days in a Gantt Chart ........................................................
26.5.1.1
How to Specify Weekdays as Nonworking Days...............................................
26.5.1.2
How to Identify Specific Dates as Nonworking Days .......................................
26.5.2
How to Apply Read-Only Values to Gantt Chart Features......................................
26.5.3
Customizing the Time Axis of a Gantt Chart .............................................................
26.5.3.1
How to Create and Use a Custom Time Axis......................................................
26.6
Printing a Gantt Chart ...........................................................................................................
26.6.1
Print Options ...................................................................................................................
26.6.2
Action Listener to Handle the Print Event..................................................................
26.7
Using Gantt Charts as a Drop Target or Drag Source ......................................................

27

26-8
26-9
26-10
26-11
26-12
26-14
26-16
26-17
26-17
26-18
26-19
26-20
26-20
26-21
26-22
26-22
26-22
26-23
26-23
26-24
26-24
26-25
26-26
26-26
26-27
26-28

Using Hierarchy Viewer Components
27.1
About Hierarchy Viewer Components.................................................................................
27.1.1
End User and Presentation Features..............................................................................
27.1.1.1
Layouts........................................................................................................................
27.1.1.2
Navigation ..................................................................................................................
27.1.1.3
Tilt Panning ................................................................................................................
27.1.1.4
Control Panel..............................................................................................................
27.1.1.5
Printing........................................................................................................................
27.1.1.6
Bi-directional Support...............................................................................................
27.1.1.7
Disable Features.........................................................................................................
27.1.1.8
State Management .....................................................................................................
27.1.2
Hierarchy Viewer Use Cases and Examples.................................................................
27.1.3
Additional Functionality for Hierarchy Viewer Components...................................
27.2
Using Hierarchy Viewer Components..................................................................................
27.2.1
Configuring Hierarchy Viewer Components ...............................................................
27.2.2
How to Add a Hierarchy Viewer to a Page ..................................................................
27.2.3
What Happens When You Add a Hierarchy Viewer to a Page ...............................
27.2.4
What You May Need to Know About How HTML Rendering...............................
27.3
Managing Nodes in a Hierarchy Viewer............................................................................
27.3.1
How to Specify Node Content ......................................................................................

27-1
27-1
27-1
27-3
27-4
27-4
27-6
27-6
27-6
27-7
27-7
27-7
27-8
27-8
27-9
27-12
27-14
27-14
27-16

xix

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.1
Customizing the Appearance Use Cases and Examples.............................................
28.1.2
Additional Functionality for Customizing the Appearance .....................................
28.2
Changing the Style Properties of a Component .................................................................
28.2.1
How to Set an Inline Style ...............................................................................................
28.2.2
How to Set a Style Class...................................................................................................
28.3
Enabling End Users to Change an Application’s ADF Skin .............................................
28.3.1
How to Enable End Users Change an Application's ADF Skin .................................
28.3.2
What Happens at Runtime: Changing an Application's ADF Skin .........................

28-1
28-3
28-3
28-4
28-4
28-6
28-6
28-7
28-8

29 Internationalizing and Localizing Pages
29.1
About Internationalizing and Localizing ADF Faces Pages ..............................................
29.1.1
Internationalizing and Localizing Pages Use Cases and Examples ..........................
29.1.2
Additional Functionality for Internationalizing and Localizing Pages ....................
29.2
Using Automatic Resource Bundle Integration in JDeveloper .........................................
29.2.1
How to Set Resource Bundle Options............................................................................
29.2.2
What Happens When You Set Resource Bundle Options ..........................................
29.2.3
How to Create an Entry in a JDeveloper-Generated Resource Bundle ....................
xx

29-1
29-2
29-3
29-4
29-5
29-6
29-7

29.2.4
29.3
29.3.1
29.3.2
29.3.3
29.3.4
29.3.5
29.3.6
29.4
29.4.1
29.4.2
29.4.3
29.5
29.5.1

What Happens When You Create an Entry in a JDeveloper-Generated Resource
Bundle 29-8
Manually Defining Resource Bundles and Locales ............................................................ 29-8
How to Define the Base Resource Bundle..................................................................... 29-9
How to Edit a Resource Bundle File ............................................................................ 29-12
How to Register Locales and Resource Bundles in Your Application.................... 29-14
How to Use Resource Bundles in Your Application ................................................. 29-15
What You May Need to Know About ADF Skins and Control Hints .................... 29-16
What You May Need to Know About Overriding a Resource Bundle in a Customizable
Application 29-16
Configuring Pages for an End User to Specify Locale at Runtime ................................. 29-17
How to Configure a Page for an End User to Specify Locale................................... 29-17
What Happens When You Configure a Page to Specify Locale .............................. 29-18
What Happens at Runtime When an End User Specifies a Locale.......................... 29-19
Configuring Optional ADF Faces Localization Properties .............................................. 29-19
How to Configure Optional Localization Properties ................................................ 29-20

30 Developing Accessible ADF Faces Pages
30.1
30.1.1
30.1.2
30.2
30.2.1
30.2.2
30.3
30.3.1
30.3.2
30.3.3
30.3.4
30.3.5
30.4
30.4.1
30.4.2
30.4.3
30.4.4
30.4.5
30.4.6
30.5
30.5.1

31

About Accessibility Support In ADF Faces..........................................................................
ADF Faces Accessibility Support Use Cases and Examples.......................................
Additional Information for Accessibility Support in ADF Pages..............................
Configuring Accessibility Support In ADF Faces ...............................................................
Accessibility Support Guidelines at Sign-In .................................................................
How to Configure Accessibility Support in trinidad-config.xml ..............................
Specifying Component-Level Accessibility Properties ......................................................
ADF Faces Component Accessibility Guidelines.........................................................
Using ADF Faces Table Components in Screen Reader Mode ................................
Data Visualization Components Accessibility Guidelines .......................................
How to Define Access Keys for an ADF Faces Component .....................................
How to Define Localized Labels and Access Keys ....................................................
Creating Accessible Pages ....................................................................................................
How to Use Partial Page Rendering ............................................................................
How to Use Scripting .....................................................................................................
How to Use Styles...........................................................................................................
How to Use Page Structures and Navigation.............................................................
How to Use Images and Tables ....................................................................................
How to Use WAI-ARIA Landmark Regions ..............................................................
Running Accessibility Audit Rules .....................................................................................
How to Create and Run an Audit Profile....................................................................

30-1
30-2
30-2
30-3
30-3
30-5
30-6
30-6
30-11
30-11
30-13
30-14
30-15
30-17
30-17
30-20
30-20
30-22
30-23
30-23
30-23

Creating Custom ADF Faces Components
31.1
About Custom ADF Faces Components...............................................................................
31.1.1
Developing a Custom Component with JDeveloper...................................................
31.1.2
An Example Custom Component ..................................................................................
31.2
Setting Up the Workspace and Starter Files.........................................................................
31.2.1
How to Set Up the JDeveloper Custom Component Environment ........................

31-1
31-2
31-5
31-9
31-10

xxi

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

xxii

About Drag and Drop Functionality..................................................................................... 33-1

33.1.1
33.2
33.3
33.3.1
33.3.2
33.3.3
33.4
33.4.1
33.4.2
33.5
33.5.1
33.6
33.6.1
33.6.2
33.7
33.7.1
33.7.2
33.8
33.8.1
33.9
33.9.1

Additional Functionality for Drag and Drop ............................................................... 33-4
Adding Drag and Drop Functionality for Attributes ......................................................... 33-4
Adding Drag and Drop Functionality for Objects .............................................................. 33-5
How to Add Drag and Drop Functionality for a Single Object ................................. 33-6
What Happens at Runtime .............................................................................................. 33-8
What You May Need to Know About Using the ClientDropListener...................... 33-9
Adding Drag and Drop Functionality for Collections ..................................................... 33-10
How to Add Drag and Drop Functionality for Collections...................................... 33-10
What You May Need to Know About the dragDropEndListener........................... 33-12
Adding Drag and Drop Functionality for Components .................................................. 33-13
How to Add Drag and Drop Functionality for Components................................... 33-13
Adding Drag and Drop Functionality Into and Out of a panelDashboard Component..........
33-15
How to Add Drag and Drop Functionality Into a panelDashboard Component . 33-16
How to Add Drag and Drop Functionality Out of a panelDashboard Component..........
33-18
Adding Drag and Drop Functionality to a Calendar ....................................................... 33-20
How to Add Drag and Drop Functionality to a Calendar........................................ 33-20
What You May Need to Know About Dragging and Dropping in a Calendar..... 33-22
Adding Drag and Drop Functionality for DVT Graphs................................................... 33-22
How to Add Drag and Drop Functionality for a DVT Graph.................................. 33-22
Adding Drag and Drop Functionality for DVT Gantt Charts ......................................... 33-24
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
35.1.1
35.2
35.3
35.3.1
35.4
35.5
35.6

Part VII

About the Active Data Service ...............................................................................................
Active Data Service Use Cases and Examples..............................................................
Process Overview for Using Active Data Service ...............................................................
Implement the ActiveModel Interface in a Managed Bean ...............................................
What You May Need to Know About Read Consistency...........................................
Pass the Event Into the Active Data Service.........................................................................
Register the Data Update Event Listener .............................................................................
Configure the ADF Component to Display Active Data ...................................................

35-1
35-2
35-2
35-3
35-6
35-6
35-7
35-8

Appendixes

xxiii

A

ADF Faces Configuration
A.1
About 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
Enabling the Application for Real User Experience Insight..................................
A.2.3.7
Assertions .....................................................................................................................
A.2.3.8
Profiling.........................................................................................................................
A.2.3.9
Dialog Prefix.................................................................................................................
A.2.3.10
Compression for CSS Class Names...........................................................................
A.2.3.11
Control Caching When You Have Multiple ADF Skins in an Application ........
A.2.3.12
Test Automation ..........................................................................................................
A.2.3.13
UIViewRoot Caching ..................................................................................................
A.2.3.14
Themes and Tonal Styles ............................................................................................
A.2.3.15
Partial Page Rendering ...............................................................................................
A.2.3.16
Partial Page Navigation ..............................................................................................
A.2.3.17
JavaScript Partitioning ................................................................................................
A.2.3.18
Framebusting ...............................................................................................................
A.2.3.19
Suppressing Auto-Generated Component IDs .....................................................
A.2.3.20
ADF Faces Caching Filter .........................................................................................
A.2.3.21
Configuring Native Browser Context Menus for Command Links...................
A.2.3.22
Session Timeout Warning ........................................................................................
A.2.3.23
JSP Tag Execution in HTTP Streaming...................................................................
A.2.4
What You May Need to Know About Other Context Parameters in web.xml .......
A.3
Configuration in faces-config.xml .........................................................................................
A.3.1
How to Configure for ADF Faces in faces-config.xml.................................................
A.4
Configuration in adf-config.xml ............................................................................................
A.4.1
How to Configure ADF Faces in adf-config.xml..........................................................
A.4.2
Defining Caching Rules for ADF Faces Caching Filter ...............................................
A.4.3
Configuring Flash as Component Output Format.......................................................
A.5
Configuration in adf-settings.xml .........................................................................................
A.5.1
How to Configure for ADF Faces in adf-settings.xml.................................................
A.5.2
What You May Need to Know About Elements in adf-settings.xml ........................
A.5.2.1
Help System ...............................................................................................................
A.5.2.2
Caching Rules.............................................................................................................
A.6
Configuration in trinidad-config.xml ...................................................................................
A.6.1
How to Configure ADF Faces Features in trinidad-config.xml.................................
A.6.2
What You May Need to Know About Elements in trinidad-config.xml ..................
A.6.2.1
Animation Enabled ...................................................................................................
A.6.2.2
Skin Family .................................................................................................................
A.6.2.3
Time Zone and Year ..................................................................................................

xxiv

A-1
A-1
A-2
A-3
A-4
A-4
A-5
A-6
A-6
A-6
A-6
A-7
A-7
A-7
A-7
A-8
A-8
A-8
A-8
A-8
A-9
A-9
A-9
A-11
A-11
A-12
A-12
A-13
A-13
A-14
A-14
A-15
A-15
A-16
A-17
A-18
A-18
A-19
A-19
A-19
A-20
A-21
A-22
A-22
A-22
A-23

A.6.2.4
Enhanced Debugging Output..................................................................................
A.6.2.5
Page Accessibility Level ...........................................................................................
A.6.2.6
Language Reading Direction ...................................................................................
A.6.2.7
Currency Code and Separators for Number Groups and Decimal Points........
A.6.2.8
Formatting Dates and Numbers Locale .................................................................
A.6.2.9
Output Mode..............................................................................................................
A.6.2.10
Number of Active PageFlowScope Instances........................................................
A.6.2.11
File Uploading............................................................................................................
A.6.2.12
Custom File Uploaded Processor ............................................................................
A.6.2.13
Client-Side Validation and Conversion..................................................................
A.6.3
What You May Need to Know About Configuring a System Property ...................
A.7
Configuration in trinidad-skins.xml .....................................................................................
A.8
Using the RequestContext EL Implicit Object .....................................................................
A.9
Performance Tuning ................................................................................................................

B

A-23
A-23
A-24
A-24
A-25
A-25
A-25
A-25
A-26
A-26
A-26
A-27
A-27
A-29

Message Keys for Converter and Validator Messages
B.1
B.2
B.3
B.3.1
B.3.2
B.3.3
B.3.4
B.3.5
B.3.6
B.3.7
B.3.8
B.3.9

About ADF Faces Default Messages .......................................................................................
Message Keys and Setter Methods ..........................................................................................
Converter and Validator Message Keys and Setter Methods..............................................
af:convertColor....................................................................................................................
af:convertDateTime ............................................................................................................
af:convertNumber...............................................................................................................
af:validateByteLength ........................................................................................................
af:validateDateRestriction .................................................................................................
af:validateDateTimeRange ................................................................................................
af:validateDoubleRange.....................................................................................................
af:validateLength ................................................................................................................
af:validateRegExp ...............................................................................................................

B-1
B-2
B-2
B-2
B-2
B-3
B-4
B-5
B-5
B-6
B-7
B-8

C Keyboard Shortcuts
About Keyboard Shortcuts ....................................................................................................... C-1
Tab Traversal .............................................................................................................................. C-1
Tab Traversal Sequence on a Page ................................................................................... C-2
Tab Traversal Sequence in a Table ................................................................................... C-2
Shortcut Keys.............................................................................................................................. C-4
Accelerator Keys ................................................................................................................. C-4
Access Keys.......................................................................................................................... C-5
Shortcut Keys for Common Components ....................................................................... C-8
Shortcut Keys for Screen Reader Mode ........................................................................... C-9
Shortcut Keys for Rich Text Editor Component............................................................. C-9
Shortcut Keys for Table, Tree, and Tree Table Components...................................... C-10
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

C.1
C.2
C.2.1
C.2.2
C.3
C.3.1
C.3.2
C.3.3
C.3.4
C.3.5
C.3.6
C.3.7

xxv

C.4
C.5

Default Cursor or Focus Placement....................................................................................... C-21
The Enter Key ........................................................................................................................... C-21

D Quick Start Layout Themes
E Code Samples
E.1
E.1.1
E.2
E.2.1
E.2.2

xxvi

Samples for Chapter 4, "Using ADF Faces Client-Side Architecture"................................
The adf-js-partitions.xml File ............................................................................................
Samples for Chapter 31, "Creating Custom ADF Faces Components" ..............................
Event Code for JavaScript..................................................................................................
Example Tag Library Descriptor File Code ....................................................................

E-1
E-1
E-8
E-8
E-9

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 Administrator’s Guide for Oracle Application Development
Framework
Oracle Fusion Middleware Desktop Integration Developer's Guide for Oracle Application
Development Framework

xxvii

■

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:

xxviii

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.

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 Section revised to correct content.
ADF Faces"

xxix

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
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.
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.

Note:

1.2 ADF Faces Framework
ADF Faces framework offers complete rich functionality, including the following;
Introduction to ADF Faces

1-1

ADF Faces 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."

1-2 Web User Interface Developer's Guide for Oracle Application Development Framework

ADF Faces Framework

■

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."

Introduction to ADF Faces

1-3

ADF Faces Components

■

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."

1-4 Web User Interface Developer's Guide for Oracle Application Development Framework

ADF Faces Components

■

–

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."
Introduction to ADF Faces

1-5

ADF Faces Components

■

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.

1-6 Web User Interface Developer's Guide for Oracle Application Development Framework

2
ADF Faces Demo Application

2

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.

ADF Faces Demo Application

2-1

About the ADF Faces Demonstration Application

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.

2-2 Web User Interface Developer's Guide for Oracle Application Development Framework

About the ADF Faces Demonstration Application

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.

ADF Faces Demo Application

2-3

About the ADF Faces Demonstration Application

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.

2-4 Web User Interface Developer's Guide for Oracle Application Development Framework

About the ADF Faces Demonstration Application

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

ADF Faces Demo Application

2-5

About the ADF Faces Demonstration Application

■

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.

2-6 Web User Interface Developer's Guide for Oracle Application Development Framework

About the ADF Faces Demonstration Application

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

ADF Faces Demo Application

2-7

About the ADF Faces Demonstration Application

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.

2-8 Web User Interface Developer's Guide for Oracle Application Development Framework

About the ADF Faces Demonstration Application

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.

ADF Faces Demo Application

2-9

Downloading and Installing the ADF Faces Demo Application

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.

2-10 Web User Interface Developer's Guide for Oracle Application Development Framework

3
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
Getting Started with ADF Faces and JDeveloper

3-1

Creating an Application Workspace

■

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.
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.

Note:

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.
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.

3-2 Web User Interface Developer's Guide for Oracle Application Development Framework

Creating an Application Workspace

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



Faces Servlet
javax.faces.webapp.FacesServlet
1


Faces Servlet
/faces/*



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

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.

Note:

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.

Best Practice:

3-4 Web User Interface Developer's Guide for Oracle Application Development Framework

Defining Page Flows

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.

Getting Started with ADF Faces and JDeveloper

3-5

Creating a View Page

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.
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

/DisplayCustomer

edit
/EditCustomer



/EditCustomer

back
/DisplayCustomer



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.

3-6 Web User Interface Developer's Guide for Oracle Application Development Framework

Creating a View Page

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.

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

Creating a layout that works correctly in all browsers
can be time consuming. Use a predefined quick layout to avoid any
potential issues.

Best Practice:

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,

Getting Started with ADF Faces and JDeveloper

3-7

Creating a View Page

"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."
Use templates to ensure consistency and so that in the
future, you can easily update multiple pages in an application.

Best Practice:

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."
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).

Best Practice:

3-8 Web User Interface Developer's Guide for Oracle Application Development Framework

Creating a View Page

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."

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."
Note:

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







Example 3–4 shows a .jspx page when it is first created by JDeveloper.

Getting Started with ADF Faces and JDeveloper

3-9

Creating a View Page

Example 3–4 Declarative JSPX Page Source Created by JDeveloper










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
























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;
3-10 Web User Interface Developer's Guide for Oracle Application Development Framework

Creating a View Page

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;
}
}

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.

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



javax.faces.STATE_SAVING_METHOD
client


javax.faces.PARTIAL_STATE_SAVING
false


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

Getting Started with ADF Faces and JDeveloper

3-11

Creating a View Page

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.
org.apache.myfaces.trinidad.CHECK_FILE_MODIFICATION
false


Whether the 'Generated by...' comment at the bottom of ADF Faces
HTML pages should contain version number information.
oracle.adf.view.rich.versionString.HIDDEN
false


javax.faces.FACELETS_SKIP_XML_INSTRUCTIONS
true


javax.faces.FACELETS_SKIP_COMMENTS
true


javax.faces.FACELETS_DECORATORS

oracle.adfinternal.view.faces.facelets.rich.AdfTagDecorator




javax.faces.FACELETS_RESOURCE_RESOLVER


oracle.adfinternal.view.faces.facelets.rich.AdfFaceletsResourceResolver



trinidad
org.apache.myfaces.trinidad.webapp.TrinidadFilter


trinidad
Faces Servlet
FORWARD
REQUEST


Faces Servlet
javax.faces.webapp.FacesServlet
1


resources
org.apache.myfaces.trinidad.webapp.ResourceServlet


BIGRAPHSERVLET
oracle.adf.view.faces.bi.webapp.GraphServlet



3-12 Web User Interface Developer's Guide for Oracle Application Development Framework

Creating a View Page

BIGAUGESERVLET
oracle.adf.view.faces.bi.webapp.GaugeServlet


MapProxyServlet
oracle.adf.view.faces.bi.webapp.MapProxyServlet


Faces Servlet
/faces/*


resources
/adf/*


resources
/afr/*


BIGRAPHSERVLET
/servlet/GraphServlet/*


BIGAUGESERVLET
/servlet/GaugeServlet/*


MapProxyServlet
/mapproxy/*


resources
/bi/*


swf
application/x-shockwave-flash


amf
application/x-amf



Note: The Facelets context parameters are only created if you create
a Facelets page.

In the faces-config.xml file, when you create a JSF page, JDeveloper creates an
entry that defines the default render kit (used to display the components in an HTML
client) for ADF Faces, as shown in Example 3–8.
Example 3–8 Generated faces-config.xml File




Getting Started with ADF Faces and JDeveloper

3-13

Creating a View Page

oracle.adf.rich



An entry in the trinidad-config.xml file defines the default skin used by the user
interface (UI) components in the application, as shown in Example 3–9.
Example 3–9 Generated trinidad-config.xml File


fusionFx
v2


When the page is first displayed in JDeveloper, it is displayed in the visual editor
(accessed by clicking the Design tab), which allows you to view the page in a
WYSIWYG environment. You can also preview your page in a browser window by
clicking the Preview tab, or view the source for the page in the source editor by
clicking the Source tab. The Structure window located in the lower left-hand corner of
JDeveloper, provides a hierarchical view of the page.

3.4.3 What You May Need to Know About Updating Your Application to Use the
Facelets Engine
JSF 2.0 web applications can run using either the Facelets engine or JSP servlet engine.
By default, documents with the *.jsf and *.xhtml extensions are handled by the
Facelets engine, while documents with the *.jsp and *.jspx extensions are handled
by the JSP engine. However, this behavior may be changed by setting the
javax.faces.FACELETS_VIEW_MAPPINGS context parameter in the web.xml file.
Because ADF Faces allows JSP pages to be run with the Facelets engine, you may
decide that you want an existing application of JSP pages to use the Facelets engine. To
do that, insert the code shown in Example 3–10 into your web.xml page.
Example 3–10 web.xml Code for Running Both JSP and Facelets Pages Using the
Facelets Engine

javax.faces.FACELETS_VIEW_MAPPINGS

*.jsf; *.jspx


javax.faces.FACELETS_SKIP_COMMENTS
true


javax.faces.FACELETS_DECORATORS

oracle.adfinternal.view.faces.facelets.rich.AdfTagDecorator




javax.faces.FACELETS_RESOURCE_RESOLVER

3-14 Web User Interface Developer's Guide for Oracle Application Development Framework

Creating a View Page


oracle.adfinternal.view.faces.facelets.rich.AdfFaceletsResourceResolver



You then must redeploy your ADF Faces libraries.
Note that if you do change your application to use the Facelets engine, then your
application will use JSF partial state saving, which is not currently compatible with
ADF Faces. You will need to explicitly add the entry shown in Example 3–11.
Once this incompatibility is resolved (as we expect to happen in future releases), you
should re-enable partial state saving by removing the entry. Check your current release
notes at
http://www.oracle.com/technetwork/developer-tools/jdev/documenta
tion/index.html for the latest information on partial state saving support.
Example 3–11

Add this web.xml Code When Using Facelets Engine


javax.faces.PARTIAL_STATE_SAVING
false


When you switch from the servlet engine to the Facelets
engine, you may find certain parts of your application do not function
as expected. For example, if you have any custom JSP tags, these tags
will need to be reimplemented to work with the Facelets engine. For
more information, refer to the ADF Faces release notes.

Note:

3.4.4 What You May Need to Know About Automatic Component Binding
Backing beans are managed beans that contain logic and properties for UI components
on a JSF page (for more information about managed beans, see Section 3.6, "Creating
and Using Managed Beans"). If when you create your JSF page you choose to
automatically expose UI components by selecting one of the choices in the Page
Implementation option of the Create JSF Page dialog, JDeveloper automatically creates
a backing bean (or uses a managed bean of your choice) for the page. For each
component you add to the page, JDeveloper then inserts a bean property for that
component, and uses the binding attribute to bind component instances to those
properties, allowing the bean to accept and return component instances.
Specifically, JDeveloper does the following when you use automatic component
binding:
■

■

Creates a JavaBean using the same name as the JSP or JSPX file, and places it in the
view.backing package (if you elect to have JDeveloper create a backing bean).
Creates a managed bean entry in the faces-config.xml file for the backing
bean. By default, the managed bean name is backing_ and the
bean uses the request scope (for more information about scopes, see Section 5.6,
"Object Scope Lifecycles").

Getting Started with ADF Faces and JDeveloper

3-15

Creating a View Page

JDeveloper does not create managed bean property entries in
the faces-config.xml file. If you wish the bean to be instantiated
with certain property values, you must perform this configuration in
the faces-config.xml file manually. For more information, see
Section A.3.1, "How to Configure for ADF Faces in faces-config.xml."

Note:

■

■

On the newly created or selected bean, adds a property and accessor methods for
each component tag you place on the JSP. JDeveloper binds the component tag to
that property using an EL expression as the value for its binding attribute.
Deletes properties and methods for any components deleted from the page.

Once the page is created and components added, you can then declaratively add
method binding expressions to components that use them by double-clicking the
component in the visual editor, which launches an editor that allows you to select the
managed bean and method to which you want to bind the attribute. When automatic
component binding is used on a page and you double-click the component, skeleton
methods to which the component may be bound are automatically created for you in
the page’s backing bean. For example, if you add a command button component and
then double-click it in the visual editor, the Bind Action Property dialog displays the
page’s backing bean along with a new skeleton action method, as shown in Figure 3–6.
Figure 3–6 Bind Action Property Dialog

You can select from one these methods, or if you enter a new method name,
JDeveloper automatically creates the new skeleton method in the page's backing bean.
You must then add the logic to the method.
When automatic component binding is not used on a page,
you must select an existing managed bean or create a new backing
bean to create the binding.

Note:

For example, suppose you created a JSF page with the file name myfile.jspx. If you
chose to let JDeveloper automatically create a default backing bean, then JDeveloper
creates the backing bean as view.backing.MyFile.java, and places it in the \src
directory of the ViewController project. The backing bean is configured as a
managed bean in the faces-config.xml file, and the default managed bean name is
backing_myfile.
Example 3–12 shows the code on a JSP that uses automatic component binding, and
contains form, inputText, and commandButton components.
Example 3–12

JSF Page Code with Automatic Component Binding


3-16 Web User Interface Developer's Guide for Oracle Application Development Framework

Creating a View Page









Example 3–13 shows the corresponding code on the backing bean.
Example 3–13

Backing Bean Code Using Automatic Component Binding

package view.backing;
import
import
import
import

oracle.adf.view.rich.component.rich.RichDocument;
oracle.adf.view.rich.component.rich.RichForm;
oracle.adf.view.rich.component.rich.input.RichInputText;
oracle.adf.view.rich.component.rich.nav.RichCommandButton;

public class MyFile {
private RichForm f1;
private RichDocument d1;
private RichInputText it1;
private RichCommandButton cb1;
public void setForm1(RichForm f1) {
this.form1 = f1;
}
public RichForm getF1() {
return f1;
}
public void setD1(RichDocument d1) {
this.d1 = d1;
}
public RichDocument getD1() {
return d1;
}
public void setIt1(RichInputText it1) {
this.inputText1 = inputText1;
}
public RichInputText getInputText1() {
return inputText1;
}
public void setCb1(RichCommandButton cb1) {
this.commandButton1 = commandButton1;
}
public RichCommandButton getCb1() {
return cb1;
}

Getting Started with ADF Faces and JDeveloper

3-17

Creating a View Page

public String cb1_action() {
// Add event code here...
return null;
}
}

Example 3–14 shows the code added to the faces-config.xml file to register the
page’s backing bean as a managed bean.
Example 3–14

Registration for a Backing Bean


backing_MyFile
view.backing.MyFile
request


Instead of registering the managed bean in the
faces-config.xml file, if you are using Facelets, you can elect to
use annotations in the backing bean for registration. For more
information about using annotations in managed and backing beans,
see the Java EE 6 tutorial at
http://www.oracle.com/technetwork/java/index.html.

Note:

In addition, when you edit a Java file that is a backing bean for a JSF page, a method
binding toolbar appears in the source editor for you to bind appropriate methods
quickly and easily to selected components in the page. When you select an event,
JDeveloper creates the skeleton method for the event, as shown in Figure 3–7.
Figure 3–7 You Can Declaratively Create Skeleton Methods in the Source Editor

3-18 Web User Interface Developer's Guide for Oracle Application Development Framework

Creating a View Page

Once you create a page, you can turn automatic component binding off or on, and you
can also change the backing bean to a different Java class. Open the JSP in the visual
Editor and from the JDeveloper menu, choose Design > Page Properties. Here you can
select or deselect the Auto Bind option, and change the managed bean class. Click
Help for more information about using the dialog.
If you turn automatic binding off, nothing changes in the
binding attributes of existing bound components in the page. If you
turn automatic binding on, all existing bound components and any
new components that you insert are bound to the selected backing
bean. If automatic binding is on and you change the bean selection, all
existing bindings and new bindings are switched to the new bean.

Note:

You can always access the backing bean for a JSF page from the page editor by
right-clicking the page, choosing Go to, and then choosing the bean from the list of
beans associated with the JSP.

3.4.5 How to Add ADF Faces Components to JSF Pages
Once you have created a page, you can use the Component Palette to drag and drop
components onto the page. JDeveloper then declaratively adds the necessary page
code and sets certain values for component attributes.
Tip: For detailed procedures and information about adding and
using specific ADF Faces components, see Part IV, "Using Common
ADF Faces Components".

You cannot use ADF Faces components on the same page as
MyFaces Trinidad components (tr: tags) or other Ajax-enabled
library components. You can use Trinidad HTML tags (trh:) on the
same page as ADF Faces components, however you may experience
some browser layout issues. You should always attempt to use only
ADF Faces components to achieve your layout.
Note:

Note that your application may contain a mix of pages built using
either ADF Faces or other components.
To add ADF Faces components to a page:
1. In the Application Navigator, double click a JSF page to open it in the editor.
2.

If the Component Palette is not displayed, from the menu choose View >
Component Palette. By default, the Component Palette is displayed in the upper
right-hand corner of JDeveloper.

3.

In the Component Palette, use the dropdown menu to choose ADF Faces.
If you have chosen to create a Facelets page, then only a subset
of ADF Faces components are available to use. You may need to use
standard JSF components instead. These are available by selecting JSF
from the dropdown menu.
Note:

Getting Started with ADF Faces and JDeveloper

3-19

Creating a View Page

Tip: If the ADF Faces page is not available in the Component Palette,
then you need to add the ADF Faces tag library to the project.

For a JSPX file:
1.

Right-click inside the Component Palette and choose Edit Tab Libraries.

2.

In the Customize Component Palette dialog, shuttle ADF Faces
Components to Selected Libraries, and click OK.

For a Facelets file:
1.

Right-click the project node and choose Project Properties.

2.

Select JSP Tag Libraries to add the ADF Faces library to the project. For
additional help, click Help or press F1.

The components are contained in five accordion panels: General Controls (which
contains components like buttons, icons, and menus), Text and Selection, Data
Views (which contains components like tables and trees), Menus and Toolbars,
Layout, and Operations.
Figure 3–8 shows the Component Palette displaying the general controls for ADF
Faces.
Figure 3–8 Component Palette in JDeveloper

4.

Select the component you wish to use and drag it onto the page.

3-20 Web User Interface Developer's Guide for Oracle Application Development Framework

Creating a View Page

JDeveloper redraws the page in the visual editor with the newly added
component. In the visual editor, you can directly select components on the page
and use the resulting context menu to add more components.
Tip: You can also drag and drop components from the palette into
the Structure window or directly into the code in the source editor.

You can always add components by directly editing the page in the
source editor. To view the page in the source editor, click the Source
tab at the bottom of the window.

3.4.6 What Happens When You Add Components to a Page
When you drag and drop components from the Component Palette onto a JSF page,
JDeveloper adds the corresponding code to the JSF page. This code includes the tag
necessary to render the component, as well as values for some of the component
attributes. Example 3–15 shows the code when you drop an Input Text and a Button
component from the palette.
Example 3–15

JDeveloper Declaratively Adds Tags to a JSF Page




If you chose to use automatic component binding, then
JDeveloper also adds the binding attribute with its value bound to
the corresponding property on the page’s backing bean. For more
information, see Section 3.4.4, "What You May Need to Know About
Automatic Component Binding."
Note:

When you drop a component that contains mandatory child components (for example
a table or a list), JDeveloper launches a wizard where you define the parent and also
each of the child components. Figure 3–9 shows the Table wizard used to create a table
component and the table’s child column components.

Getting Started with ADF Faces and JDeveloper

3-21

Creating a View Page

Figure 3–9 Table Wizard in JDeveloper

Example 3–16 shows the code created when you use the wizard to create a table with
three columns, each of which uses an outputText component to display data.
Example 3–16

Declarative Code for a Table Component













3.4.7 How to Set Component Attributes
Once you drop components onto a page you can use the Property Inspector (displayed
by default at the bottom right of JDeveloper) to set attribute values for each
component.
Tip: If the Property Inspector is not displayed, choose View >
Property Inspector from the main menu.

Figure 3–10 shows the Property Inspector displaying the attributes for an inputText
component.

3-22 Web User Interface Developer's Guide for Oracle Application Development Framework

Creating a View Page

Figure 3–10 JDeveloper Property Inspector

The Property Inspector has sections that group similar properties together. For
example, the Property Inspector groups commonly used attributes for the inputText
component in the Common section, while properties that affect how the component
behaves are grouped together in the Behavior section. Figure 3–11 shows the Behavior
section of the Property Inspector for an inputText component.
Figure 3–11 Behavior Section of the Property Inspector

To set component attributes:
1. Select the component, in the visual editor, in the Structure window, or by selecting
the tag directly in the source editor.
2.

In the Property Inspector, expand the section that contains the attribute you wish
to set.
Tip: Some attributes are displayed in more than one section.
Entering or changing the value in one section will also change it in
any other sections. You can search for an attribute by entering the
attribute name in the search field at the top of the inspector.

3.

Either enter values directly into the fields, or if the field contains a dropdown list,
use that list to select a value. You can also use the dropdown to the right of the
field, which launches a popup containing tools you can use to set the value. These
tools are either specific property editors (opened by choosing Edit) or the
Expression Builder, which you can use to create EL expressions for the value
(opened by choosing Expression Builder). For more information about using the
Getting Started with ADF Faces and JDeveloper

3-23

Creating EL Expressions

Expression Builder, see Section 3.5, "Creating EL Expressions." This popup also
displays a description of the property, as shown in Figure 3–12.
Figure 3–12 Property Tools and Help

3.4.8 What Happens When You Use the Property Inspector
When you use the Property Inspector to set or change attribute values, JDeveloper
automatically changes the page source for the attribute to match the entered value.
Tip: You can always change attribute values by directly editing the
page in the source editor. To view the page in the source editor, click
the Source tab at the bottom of the window.

3.5 Creating EL Expressions
You use EL expressions throughout an ADF Faces application to bind attributes to
object values determined at runtime. For example, #{UserList.selectedUsers}
might reference a set of selected users, #{user.name} might reference a particular
user's name, while #{user.role == 'manager'} would evaluate whether a user is
a manager or not. At runtime, a generic expression evaluator returns the List,
String, and boolean values of these respective expressions, automating access to
the individual objects and their properties without requiring code.
At runtime, the value of certain JSF UI components (such as an inputText
component or an outputText component) is determined by its value attribute.
While a component can have static text as its value, typically the value attribute will
contain an EL expression that the runtime infrastructure evaluates to determine what
data to display. For example, an outputText component that displays the name of
the currently logged-in user might have its value attribute set to the expression
#{UserInfo.name}. Since any attribute of a component (and not just the value
attribute) can be assigned a value using an EL expression, it's easy to build dynamic,
data-driven user interfaces. For example, you could hide a component when a set of
objects you need to display is empty by using a boolean-valued expression like #{not
empty UserList.selectedUsers} in the UI component's rendered attribute. If
the list of selected users in the object named UserList is empty, the rendered
attribute evaluates to false and the component disappears from the page.
In a typical JSF application, you would create objects like UserList as a managed
bean. The JSF runtime manages instantiating these beans on demand when any EL

3-24 Web User Interface Developer's Guide for Oracle Application Development Framework

Creating EL Expressions

expression references them for the first time. When displaying a value, the runtime
evaluates the EL expression and pulls the value from the managed bean to populate
the component with data when the page is displayed. If the user updates data in the
UI component, the JSF runtime pushes the value back into the corresponding managed
bean based on the same EL expression. For more information about creating and using
managed beans, see Section 3.6, "Creating and Using Managed Beans." For more
information about EL expressions, see the Java EE 6 tutorial at
http://www.oracle.com/technetwork/java/index.html.
When using an EL expression for the value attribute of an
editable component, you must have a corresponding set method for
the that component, or else the EL expression will evaluate to
read-only, and no updates to the value will be allowed.

Note:

For example, say you have an inputText component (whose ID is
inputText1) on a page, and you have it’s value set to
#{myBean.inputValue}. The myBean managed bean would have
to have get and set method as follows, in order for the inputText
value to be updated:
public void setIt1(RichInputText inputText1) {
this.inputText1 = inputText1;
}
public RichInputText getInputText1() {
return inputText1;
}

Along with standard EL reachable objects and operands, ADF Faces provides EL
function tags. These are tags that provide certain functionality that you can use within
an EL expression. The format tags can be used to add parameters to String messages,
and the time zone tags can be used to return time zones. For information about the
format tags, see Section 3.5.2, "How to Use the EL Format Tags." For information about
the time zone tags, see Section 11.5.3, "What You May Need to Know About Selecting
Time Zones Without the inputDate Component."

3.5.1 How to Create an EL Expression
You can create EL expressions declaratively using the JDeveloper Expression Builder.
You can access the builder from the Property Inspector.
Before you begin
It may be helpful to have an understanding of EL expressions. For more information,
see Section 3.5, "Creating EL Expressions."
To use the Expression Builder:
1. In the Property Inspector, locate the attribute you wish to modify and use the right
most dropdown menu to choose Expression Builder.
2.

Create expressions using the following features:
■

Use the Variables dropdown to select items that you want to include in the
expression. These items are displayed in a tree that is a hierarchical
representation of the binding objects. Each icon in the tree represents various
types of binding objects that you can use in an expression.

Getting Started with ADF Faces and JDeveloper

3-25

Creating EL Expressions

To narrow down the tree, you can either use the dropdown filter or enter
search criteria in the search field. The EL accessible objects exposed by ADF
Faces are located under the adfFacesContext node, which is under the JSF
Managed Beans node, as shown in Figure 3–13.
Figure 3–13 adfFacesContext Objects in the Expression Builder

Tip: For more information about these objects, see the ADF Faces
Javadoc.

Selecting an item in the tree causes it to be moved to the Expression box
within an EL expression. You can also type the expression directly in the
Expression box.
■

Use the operator buttons to add logical or mathematical operators to the
expression.

Figure 3–14 shows the Expression Builder dialog being used to create an
expression that binds to the value of a label for a component to the label
property of the explorer managed bean.

3-26 Web User Interface Developer's Guide for Oracle Application Development Framework

Creating EL Expressions

Figure 3–14 The Expression Builder Dialog

Tip: For information about using proper syntax to create EL
expressions, see the Java EE 6 tutorial at
http://download.oracle.com/javaee/index.html.

3.5.2 How to Use the EL Format Tags
ADF EL format tags allow you to create text that uses placeholder parameters, which
can then be used as the value for any component attribute that accepts a String. At
runtime, the placeholders are replaced with the parameter values.
For example, say the current user’s name is stored on a managed bean, and you want
to display that name within a message as the value of an outputText component.
You could use the formatString tag as shown in Example 3–17.
Example 3–17

Using the formatString Tag to Display a Message with a Parameter



In this example, the formatString tag takes one parameter whose key "0," resolves to
the value someBean.currentUser.
There are two different types of format tags available, formatString tags and
formatNamed tags. The formatString tags use indexed parameters, while the
formatNamed tags use named parameters. There are four tags for each type, each one
taking a different number of parameters (up to 4). For example, the formatString2
tag takes two indexed parameters, and the formatNamed4 tag takes four named
parameters.
When you use a formatNamed tag, you set both the key and the value. Example 3–18
shows a message that uses the formatNamed2 tag to display the number of files on a
specific disk. This message contains two parameters.
Getting Started with ADF Faces and JDeveloper

3-27

Creating EL Expressions

Example 3–18

Using the formatNamed2 Tag to Display a Message



3.5.3 How to Use EL Expressions Within Managed Beans
While JDeveloper creates many needed EL expressions for you, and you can use the
Expression Builder to create those not built for you, there may be times when you need
to access, set, or invoke EL expressions within a managed bean.
Example 3–19 shows how you can get a reference to an EL expression and return (or
create) the matching object.
Example 3–19

Resolving an EL Expression from a Managed Bean

public static Object resolveExpression(String expression) {
FacesContext facesContext = getFacesContext();
Application app = facesContext.getApplication();
ExpressionFactory elFactory = app.getExpressionFactory();
ELContext elContext = facesContext.getELContext();
ValueExpression valueExp =
elFactory.createValueExpression(elContext, expression,
Object.class);
return valueExp.getValue(elContext);
}

Example 3–20 shows how you can resolve a method expression.
Example 3–20

Resolving a Method Expression from a Managed Bean

public static Object resloveMethodExpression(String expression,
Class returnType,
Class[] argTypes,
Object[] argValues) {
FacesContext facesContext = getFacesContext();
Application app = facesContext.getApplication();
ExpressionFactory elFactory = app.getExpressionFactory();
ELContext elContext = facesContext.getELContext();
MethodExpression methodExpression =
elFactory.createMethodExpression(elContext, expression, returnType,
argTypes);
return methodExpression.invoke(elContext, argValues);
}

Example 3–21 shows how you can set a new object on a managed bean.
Example 3–21

Setting a New Object on a Managed Bean

public static void setObject(String expression, Object newValue) {
FacesContext facesContext = getFacesContext();
Application app = facesContext.getApplication();
ExpressionFactory elFactory = app.getExpressionFactory();
ELContext elContext = facesContext.getELContext();
ValueExpression valueExp =
elFactory.createValueExpression(elContext, expression,
Object.class);
//Check that the input newValue can be cast to the property type
//expected by the managed bean.

3-28 Web User Interface Developer's Guide for Oracle Application Development Framework

Creating and Using Managed Beans

//Rely on Auto-Unboxing if the managed Bean expects a primitive
Class bindClass = valueExp.getType(elContext);
if (bindClass.isPrimitive() || bindClass.isInstance(newValue)) {
valueExp.setValue(elContext, newValue);
}
}

3.6 Creating and Using Managed Beans
Managed beans are Java classes that you register with the application using various
configuration files. When the JSF application starts up, it parses these configuration
files and the beans are made available and can be referenced in an EL expression,
allowing access to the beans’ properties and methods. Whenever a managed bean is
referenced for the first time and it does not already exist, the Managed Bean Creation
Facility instantiates the bean by calling the default constructor method on the bean. If
any properties are also declared, they are populated with the declared default values.
Often, managed beans handle events or some manipulation of data that is best
handled at the front end. For a more complete description of how managed beans are
used in a standard JSF application, see the Java EE 6 tutorial at
http://www.oracle.com/technetwork/java/index.html.
Use managed beans to store only bookkeeping
information, for example the current user. All application data and
processing should be handled by logic in the business layer of the
application.

Best Practice:

In a standard JSF application, managed beans are registered in the
faces-config.xml configuration file.
If you plan on using Oracle ADF Model data binding and ADF
Controller, then instead of registering managed beans in the
faces-config.xml file, you may need to register them within ADF
task flows. For more information, refer to the "Using a Managed Bean
in a Fusion Web Application" section of the Oracle Fusion Middleware
Fusion Developer's Guide for Oracle Application Development Framework.

Note:

3.6.1 How to Create a Managed Bean in JDeveloper
You can create a managed bean and register it with the JSF application at the same
time using the overview editor for the faces-config.xml file.
Before you begin
It may be helpful to have an understanding of managed beans. For more information,
see Section 3.6, "Creating and Using Managed Beans."
To create and register a managed bean:
1. In the Application Navigator, open the faces-config.xml file.
2.

In the editor window, click the Overview tab.

3.

In the overview editor, click the Managed Beans tab.
Figure 3–15 shows the editor for the faces-config.xml file used by the ADF
Faces demo that contains the File Explorer application.

Getting Started with ADF Faces and JDeveloper

3-29

Creating and Using Managed Beans

Figure 3–15 Managed Beans in the faces-config.xml File

4.

Click the Add icon to add a row to the Managed Bean table.

5.

In the Create Managed Bean dialog, enter values. Click Help for more information
about using the dialog. Select the Generate Class If It Does Not Exist option if
you want JDeveloper to create the class file for you.
When determining what scope to register a managed bean
with or to store a value in, keep the following in mind:

Note:
■
■

■

Always try to use the narrowest scope possible.
If your managed bean takes part in component binding by
accepting and returning component instances (that is, if UI
components on the page use the binding attribute to bind to
component properties on the bean), then the managed bean must
be stored in request or backingBean scope. If it can’t be stored
in one of those scopes (for example, if it needs to be stored in
session scope for high availability reasons), then you need to
use the ComponentReference API. For more information, see
Section 3.6.3, "What You May Need to Know About Component
Bindings and Managed Beans."
Use the sessionScope scope only for information that is
relevant to the whole session, such as user or context information.
Avoid using the sessionScope scope to pass values from one
page to another.

For more information about the different object scopes, see Section 5.6,
"Object Scope Lifecycles."
6.

You can optionally add managed properties for the bean. When the bean is
instantiated, any managed properties will be set with the provided value. With the
bean selected in the Managed Bean table, click the New icon to add a row to the
Managed Properties table. In the Property Inspector, enter a property name (other
fields are optional).

3-30 Web User Interface Developer's Guide for Oracle Application Development Framework

Creating and Using Managed Beans

While you can declare managed properties using this editor,
the corresponding code is not generated on the Java class. You must
add that code by creating private member fields of the appropriate
type, and then by choosing the Generate Accessors menu item on the
context menu of the code editor to generate the corresponding get
and set methods for these bean properties.

Note:

3.6.2 What Happens When You Use JDeveloper to Create a Managed Bean
When you create a managed bean and elect to generate the Java file, JDeveloper
creates a stub class with the given name and a default constructor. Example 3–22
shows the code added to the MyBean class stored in the view package.
Example 3–22

Generated Code for a Managed Bean

package view;
public class MyBean {
public MyBean() {
}
}

You now must add the logic required by your page. You can then refer to that logic
using an EL expression that refers to the managed-bean-name given to the managed
bean. For example, to access the myInfo property on the my_bean managed bean, the
EL expression would be:
#{my_bean.myInfo}

JDeveloper also adds a managed-bean element to the faces-config.xml file.
Example 3–23 shows the managed-bean element created for the MyBean class.
Example 3–23

Managed Bean Configuration on the faces-config.xml File


my_bean
view.MyBean
session


3.6.3 What You May Need to Know About Component Bindings and Managed Beans
To avoid issues with managed beans, if your bean needs to use component binding
(through the binding attribute on the component), you must store the bean in
request scope. (If your application uses the Fusion technology stack, then you must
store it in backingBean scope. For more information, see the "Using a Managed Bean
in a Fusion Web Application" section in the Oracle Fusion Middleware Fusion Developer's
Guide for Oracle Application Development Framework.) However, there may be
circumstances where you can’t store the bean in request or backingBean scope. For
example, there may be managed beans that are stored in session scope so that they
can be deployed in a clustered environment, and therefore must implement the
Serializable interface. When they are serializable, managed beans that change during a
request can be distributed to other servers for fail-over. However, ADF Faces
components (and JSF components in general) are not serializable. So if a serialized
managed bean attempts to access a component using component binding, the bean
will fail serialization because the referenced component cannot be serialized. There are
Getting Started with ADF Faces and JDeveloper

3-31

Viewing ADF Faces Javadoc

also thread safety issues with components bound to serialized managed beans because
ADF Faces components are not thread safe.
When you need to store a component reference to a UI component instance in a
backing bean that is not using request or backingBean scope, you should store a
reference to the component instance using the Trinidad ComponentReference API.
The UIComponentReference.newUIComponentReference() method creates a
serializable reference object that can be used to retrieve a UIComponent instance on
the current page. Example 3–24 shows how a managed bean might use the
UIComponentReference API to get and set values for a search field.
Example 3–24

Session Scoped Managed Bean Uses the UIComponentReference API

...
private ComponentReference searchField;
...
public void setSearchField(UIInput searchField)
{
if( this.searchField == null)
this.searchField = ComponentReference.newUIComponentReference(searchField);
}
public UIInput getSearchField()
{
return searchField ==null ? null : searchField.getComponent();
}
....

Keep the following in mind when using the UIComponentReference API:
■

The API is thread safe as long as it is called on the request thread.

■

The ADF Faces component being passed in must have an ID.

■

The reference will break if the component is moved between naming containers or
if the ID on any of the ancestor naming containers has changed.

For more information about the UIComponentReference API, see the Trinidad
JavaDoc.

3.7 Viewing ADF Faces Javadoc
Often, when you are working with ADF Faces, you will need to view the Javadoc for
ADF Faces classes. You can view Javadoc from within JDeveloper.

3.7.1 How to View ADF Faces Source Code and Javadoc
You can view the ADF Faces Javadoc directly from JDeveloper.
To view Javadoc for a class:
1. From the main menu, choose Navigate > Go to Javadoc.
2.

In the Go to Javadoc dialog, enter the class name you want to view. If you don’t
know the exact name, you can either begin to type the name and JDeveloper will
provide a list of classes that match the name. ADF Faces components are in the
oracle.adf.view.rich package.

3-32 Web User Interface Developer's Guide for Oracle Application Development Framework

Viewing ADF Faces Javadoc

Tip: When in a Java class file, you can go directly to the Javadoc for a
class name reference or for a JavaScript function call by placing your
cursor on the name or function and pressing Ctrl+D.

Getting Started with ADF Faces and JDeveloper

3-33

Viewing ADF Faces Javadoc

3-34 Web User Interface Developer's Guide for Oracle Application Development Framework

Part II
Part II

Understanding ADF Faces Architecture
Part II contains the following chapters:
■

Chapter 4, "Using ADF Faces Client-Side Architecture"

■

Chapter 5, "Using the JSF Lifecycle with ADF Faces"

■

Chapter 6, "Handling Events"

■

Chapter 7, "Validating and Converting Input"

■

Chapter 8, "Rerendering Partial Page Content"

4
4

Using ADF Faces Client-Side Architecture
This chapter outlines the ADF Faces client-side architecture.
This chapter includes the following sections:
■

Section 4.1, "About Using ADF Faces Architecture"

■

Section 4.2, "Listening for Client Events"

■

Section 4.3, "Adding JavaScript to a Page"

■

Section 4.4, "Instantiating Client-Side Components"

■

Section 4.5, "Locating a Client Component on a Page"

■

Section 4.6, "Accessing Component Properties on the Client"

■

Section 4.7, "Using Bonus Attributes for Client-Side Components"

■

Section 4.8, "Understanding Rendering and Visibility"

■

Section 4.9, "JavaScript Library Partitioning"

4.1 About Using ADF Faces Architecture
ADF Faces extends the JavaServer Faces architecture, adding a client-side framework
on top of the standard server-centric model. The majority of ADF Faces components
are rendered in HTML that is generated on the server-side for a request. In addition,
ADF Faces allows component implementations to extend their reach to the client using
a client-side component and event model.
The ADF Faces framework already contains much of the functionality for which you
would ordinarily need to use JavaScript. In many cases, you can achieve rich
component functionality declaratively, without the use of JavaScript. However, there
may be times when you do need to add your own JavaScript, for example custom
processing in response to a client-side event. In these cases, you can use the client-side
framework.
The JavaScript class that you will interact with most is AdfUIComponent and its
subclasses. An instance of this class is the client-side representation of a server-side
component. You can think of a client-side component as a simple property container
with support for event handling. Client-side components primarily exist to add
behavior to the page by exposing an API contract for both application developers as
well as for the framework itself. It is this contract that allows, among other things,
toggling the enabled state of a button on the client.
Each client component has a set of properties (key/value pairs) and a list of listeners
for each supported event type. All ADF Faces JavaScript classes are prefixed with Adf
to avoid naming conflicts with other JavaScript libraries. For example,
Using ADF Faces Client-Side Architecture

4-1

About Using ADF Faces Architecture

RichCommandButton has AdfRichCommandButton, RichDocument has
AdfRichDocument, and so on.
In the client-side JavaScript layer, client components exist mostly to provide an API
contract for the framework and for developers. Because client components exist only
to store state and provide an API, they have no direct interaction with the document
object model (DOM) whatsoever. All DOM interaction goes through an intermediary
called the peer. Peers interact with the DOM generated by the Java renderer and handle
updating that state and responding to user interactions.
Peers have a number of other responsibilities, including:
■

DOM initialization and cleanup

■

DOM event handling

■

Geometry management

■

Partial page response handling

■

Child visibility change handling

This separation isolates the component and application developer from changes in the
DOM implementation of the component and also isolates the need for the application
to know whether a component is implemented in HTML DOM at all (for example the
Flash components).
In JSF, as in most component-based frameworks, an intrinsic property of the
component model is that components can be nested to form a hierarchy, typically
known as the component tree. This simply means that parent components keep track of
their children, making it possible to walk over the component tree to find
all descendents of any given component. While the full component tree exists on the
server, the ADF Faces client-side component tree is sparsely populated.
For performance optimization, client components exist only when they are required,
either due to having a clientListener handler registered on them, or because the
page developer needs to interact with a component on the client side and has
specifically configured the client component to be available. You don’t need to
understand the client framework as except for exceptional cases, you use most of the
architectural features declaratively, without having to create any code.
For example, because the framework does not create client components for every
server-side component, there may be cases where you need a client version of a
component instance. Section 4.4, "Instantiating Client-Side Components," explains how
to do this declaratively. You use the Property Inspector in JDeveloper to set properties
that determine whether a component should be rendered at all, or simply be made not
visible, as described in Section 4.8, "Understanding Rendering and Visibility."
It is also possible for JavaScript components to be present that
do not correspond to any existing server-side component. For
example, some ADF Faces components have client-side behavior that
requires popup content. These components may create
AdfRichPopup JavaScript components, even though no server-side
Java RichPopup component may exist.

Note:

Other functionality may require you to use the ADF Faces JavaScript API. For
example, Section 4.5, "Locating a Client Component on a Page," explains how to use
the API to locate a specific client-side component, and Section 4.6, "Accessing
Component Properties on the Client," documents how to access specific properties.

4-2 Web User Interface Developer's Guide for Oracle Application Development Framework

Listening for Client Events

A common issue with JavaScript-heavy frameworks is determining how best to
deliver a large JavaScript code base to the client. If all the code is in a single JavaScript
library, there will be a long download time, while splitting the JavaScript into too
many libraries will result in a large number of roundtrips. To help mitigate this issue,
ADF Faces aggregates its JavaScript code into partitions. A JavaScript library partition
contains code for components and/or features that are commonly used together. For
more information, see Section 4.9, "JavaScript Library Partitioning."

4.2 Listening for Client Events
In a traditional JSF application, if you want to process events on the client, you must
listen to DOM-level events. However, these events are not delivered in a portable
manner. The ADF Faces client-side event model is similar to the JSF events model, but
implemented on the client. The client-side event model abstracts from the DOM,
providing a component-level event model and lifecycle, which executes independently
of the server. Consequently, you do not need to listen for click events on buttons.
You can instead listen for AdfActionEvent events, which can be caused by key or
mouse events.
Events sent by clients are all subclasses of the AdfBaseEvent class. Each client event
has a source, which is the component that triggered the event. Events also have a type
(for example, action or dialog), used to determine which listeners are interested in
the event. You register a client listener on the component declaratively using the
af:clientListener tag.

4.2.1 How to Listen for Client Events
You use the af:clientListener tag to call corresponding Javascript in response to
a client event. For example, suppose you have a button that, in response to a click,
should display a "Hello World" alert. You need to first create the JavaScript function
that will respond to the event by displaying the alert. You then add the client listener
to the component that will invoke that function.
Before you begin
It may be helpful to have an understanding of client event processing. For more
information, see Section 4.2, "Listening for Client Events."
To listen for a client event:
1. Implement the JavaScript function. For example, to display the alert, you might
create the JavaScript function shown in Example 4–1.
Example 4–1 JavaScript Event Handler
function sayHello(event)
{
alert("Hello, world!")
}
2.

From the Operations panel of the Component Palette, drag and drop a Client
Listener as a child to the component that will raise the event.
Enter the function created in Step 1, as well as the type of action that the listener
should respond to. Example 4–2 shows the code that would be created for the
listener for the sayHello function.

Using ADF Faces Client-Side Architecture

4-3

Adding JavaScript to a Page

Example 4–2 Registering a Client Listener




Tip: Because the button has a registered client listener, the
framework will automatically create a client version of the
component.

When the button is clicked, because there is a client version of the component, the
AdfAction client event is invoked. Because a clientListener tag is configured to
listen for the AdfAction event, it causes the sayHello function to execute. For more
information about client-side events, see Section 6.3, "Using JavaScript for ADF Faces
Client Events."

4.3 Adding JavaScript to a Page
You can either add inline JavaScript directly to a page or you can import JavaScript
libraries into a page. When you import libraries, you reduce the page content size, the
libraries can be shared across pages, and they can be cached by the browser. You
should import JavaScript libraries whenever possible. Use inline JavaScript only for
cases where a small, page-specific script is needed.
Performance Tip: Including JavaScript only in the pages that need it
will result in better performance because those pages that do not need
it will not have to load it, as they would if the JavaScript were
included in a template. However, if you find that most of your pages
use the same JavaScript code, you may want to consider including the
script or the tag to import the library in a template.

Note, however, that if a JavaScript code library becomes too big, you
should consider splitting it into meaningful pieces and include only
the pieces needed by the page (and not in a template). This approach
will provide improved performance, because the browser cache will
be used and the HTML content of the page will be smaller.

4.3.1 How to Use Inline JavaScript
Create the JavaScript on the page and then use a clientListener tag to invoke it.
Before you begin
It may be helpful to have an understanding of adding JavaScript to a page. For more
information, see Section 4.3, "Adding JavaScript to a Page."
To use inline JavaScript:
1. Add the MyFaces Trinidad tag library to the root element of the page by adding
the code shown in bold in Example 4–3.
Example 4–3 MyFaces Trinidad Tag Library on a Page


4-4 Web User Interface Developer's Guide for Oracle Application Development Framework

Adding JavaScript to a Page

2.

In the Component Palette, from the Layout panel, in the Core Structure group,
drag and drop a Resource onto the page.
Do not use the f:verbatim tag in a page or template to
specify the JavaScript.

Note:

3.

In the Insert Resource dialog, select javascript from the dropdown menu and click
OK.

4.

Create the JavaScript on the page within the  tag.
For example, the sayHello function shown in Example 4–1 might be included in
a JSF page as shown in Example 4–4.

Example 4–4 Inline JavaScript

function sayHello()
{
alert("Hello, world!")
}

5.

In the Structure window, right-click the component that will invoke the JavaScript,
and choose Insert inside component > ADF Faces > Client Listener.

6.

In the Insert Client Listener dialog, in the Method field, enter the JavaScript
function name. In the Type field, select the event type that should invoke the
function.

4.3.2 How to Import JavaScript Libraries
Use the af:resource tag to access a JavaScript library from a page. This tag should
appear inside the document tag’s metaContainer facet.
Before you begin
It may be helpful to have an understanding of adding JavaScript to a page. For more
information, see Section 4.3, "Adding JavaScript to a Page."
To access a JavaScript library from a page:
Below the document tag, add the code shown in bold in Example 4–5 and replace
/mySourceDirectory with the relative path to the directory that holds the
JavaScript library.

1.

Example 4–5 Accessing a JavaScript Library






2.

In the Structure window, right-click the component that will invoke the JavaScript,
and choose Insert inside component > ADF Faces > Client Listener.

Using ADF Faces Client-Side Architecture

4-5

Instantiating Client-Side Components

3.

In the Insert Client Listener dialog, in the Method field, enter the fully qualified
name of the function. For example, if the sayHello function was in the
MyScripts library, you would enter MyScripts.sayHello. In the Type field,
select the event type that should invoke the function.

4.3.3 What You May Need to Know About Accessing Client Event Sources
Often when your JavaScript needs to access a client component, it is within the context
of a listener and must access the event’s source component. Use the getSource()
method to get the client component. Example 4–6 shows the sayHello function
accessing the source client component in order to display its name.
Example 4–6 Accessing a Client Event Source
function sayHello(actionEvent)
{
var component=actionEvent.getSource();
//Get the ID for the component
var id=component.getId();
alert("Hello from "+id);
}

For more information about accessing client event sources, see Section 6.3, "Using
JavaScript for ADF Faces Client Events." For more information about accessing
client-side properties, see Section 4.6, "Accessing Component Properties on the Client."
For a complete description of how client events are handled at runtime, see
Section 6.3.7, "What Happens at Runtime: How Client-Side Events Work."

4.4 Instantiating Client-Side Components
By default, the framework does not make any guarantees about which components
will have corresponding client-side component instances. To interact with a
component on the client, you will usually register a clientListener handler. When
a component has a registered clientListener handler, it will automatically have
client-side representation. You can also explicitly configure a component to be
available on the client by setting the clientComponent attribute to true.

4.4.1 How to Configure a Component to for a Client-Side Instance
You can manually configure a component to have a client side instance using the
clientComponent attribute.
Performance Tip: Only set clientComponent to true if you plan
on interacting with the component programmatically on the client.

When the framework creates a client component for its own
uses, that client component may only contain information the
framework needs at that time. For example, not all of the attributes
may be available.

Note:

4-6 Web User Interface Developer's Guide for Oracle Application Development Framework

Locating a Client Component on a Page

Before you begin
It may be helpful to have an understanding of client-side instances. For more
information, see Section 4.4, "Instantiating Client-Side Components."
To configure a component for a client-side instance:
1. In the Structure window, select the component that needs a client-side instance.
2.

In the Property Inspector, set ClientSide to true.

4.4.2 What Happens When You Set clientComponent to true
When you set the clientComponent attribute to true, the framework creates an
instance of an AdfUIComponent class for the component. This class provides the API
that you can work with on the client side and also provides basic property accessor
methods (for example, getProperty() and setProperty()), event listener
registration, and event delivery-related APIs. The framework also provides
renderer-specific subclasses (for example, AdfRichOutputText) which expose
property-specific accessor methods (for example, getText() and setText()). These
accessor methods are simply wrappers around the AdfUIComponent class’s
getProperty() and setProperty() methods and are provided for coding
convenience.
For example, suppose you have an outputText component on the page that will get
its value (and therefore the text to display) from the sayHello function. That function
must be able to access the outputText component in order to set its value. For this to
work, there must be a client-side version of the outputText component. Example 4–7
shows the JSF page code. Note that the outputText component has an id value and
the clientComponent attribute is set to true. Also, note there is no value in the
example, because that value will be set by the JavaScript.
Example 4–7 Adding a Component





Because the outputText component will now have client-side representation, the
JavaScript will be able to locate and work with it.

4.5 Locating a Client Component on a Page
When you need to find a client component that is not the source of an event, you can
use the AdfUIComponent.findComponent(expr) method. This method is similar
to the JSF UIComponent.findComponent() method, which searches for and returns
the UIComponent object with an ID that matches the specified search expression. The
AdfUIComponent.findComponent(expr) method simply works on the client
instead of the server.
Example 4–8 shows the sayHello function finding the outputText component
using the component’s ID.
Example 4–8 Finding a Client Component Using findComponent()
function sayHello(actionEvent)
{

Using ADF Faces Client-Side Architecture

4-7

Locating a Client Component on a Page

var buttonComponent=actionEvent.getSource();
//Find the client component for the "greeting" af:outputText
var greetingComponent=buttonComponent.findComponent("greeting");
//Set the value for the outputText component
greetingComponent.setValue("Hello World")
}

ADF Faces also has the
AdfPage.PAGE.findComponentByAbsoluteId(absolute expr) method. Use
this method when you want to hard-code the String for the ID. Use
AdfUIComponent.findComponent(expr) when the client ID is being retrieved
from the component.
There is also a confusingly named
AdfPage.PAGE.findComponent(clientId) method, however
this function uses implementation-specific identifiers that can change
between releases and should not be used by page authors.

Note:

4.5.1 What You May Need to Know About Finding Components in Naming Containers
If the component you need to find is within a component that is a naming container
(such as pageTemplate, subform, table, and tree), then instead of using the
AdfPage.PAGE.findComponentByAbsoluteId(absolute expr) method, use
the AdfUIComponent.findComponent(expr) method. The expression can be
either absolute or relative.
Tip: You can determine whether or not a component is a naming
container by reviewing the component tag documentation. The tag
documentation states whether a component is a naming container.

Absolute expressions use the fully qualified JSF client ID (meaning, prefixed with the
IDs of all NamingContainer components that contain the component) with a leading
NamingContainer.SEPARATOR_CHAR character, for example:
":" + (namingContainersToJumpUp * ":") + some ending portion of the
clientIdOfComponentToFind

For example, to find a table whose ID is t1 that is within a panel collection component
whose ID is pc1 contained in a region whose ID is r1 on page that uses the
myTemplate template, you might use the following:
:myTemplate:r1:pc1:t1

Alternatively, if both the components (the one doing the search and the one being
searched for) share the same NamingContainer component somewhere in the
hierarchy, you can use a relative path to perform a search relative to the component
doing the search. A relative path has multiple leading
NamingContainer.SEPARATOR_CHAR characters, for example:
":" + clientIdOfComponentToFind

In the preceding example, if the component doing the searching is also in the same
region as the table, you might use the following:

4-8 Web User Interface Developer's Guide for Oracle Application Development Framework

Accessing Component Properties on the Client

::somePanelCollection:someTable

Tip: Think of a naming container as a folder and the clientId as a
file path. In terms of folders and files, you use two sequential periods
and a slash (../) to move up in the hierarchy to another folder.
This is the same thing that the multiple colon (:) characters do in the
findComponent() expression. A single leading colon (:) means
that the file path is absolute from the root of the file structure. If there
are multiple leading colon (:) characters at the beginning of the
expression, then the first one is ignored and the others are counted,
one set of periods and a slash (../) per colon (:) character.

Note that if you were to use the
AdfPage.findComponentByAbsoluteId() method, no leading
colon is needed as, the path always absolute.
When deciding whether to use an absolute or relative path, keep the following in
mind:
■

■

If you know that the component you are trying to find will always be in the same
naming container, then use an absolute path.
If you know that the component performing the search and the component you
are trying to find will always be in the same relative location, then use a relative
path.

There are no getChildren() or getFacet() functions on the client. Instead, the
AdfUIComponent.visitChildren() function is provided to visit all children
components or facets (that is all descendents). Because ADF Faces uses a sparse
component tree (that is, client components are created on an as-needed basis, the
component that the getParent() method might return on the client may not be the
actual parent on the server (it could be any ancestor). Likewise, the components that
appear to be immediate children on the client could be any descendants. For more
information, see the ADF Faces JavaScript documentation.

4.6 Accessing Component Properties on the Client
For each built-in property on a component, convenience accessor methods are
available on the component class. For example, you can call the getValue() method
on a client component and receive the same value that was used on the server.
All client properties in ADF Faces use the getXyz function
naming convention including boolean properties. The isXyz naming
convention for boolean properties is not used.

Note:

Constants are also available for the property names on the class object. For instance,
you can use AdfRichDialog.STYLE_CLASS constant instead of using
"styleClass".
In JavaScript, it is more efficient to refer to a constant than to
code the string, as in some JavaScript execution environments, the
latter requires an object allocation on each invocation.

Note:

Using ADF Faces Client-Side Architecture

4-9

Accessing Component Properties on the Client

When a component’s property changes, the end result should be that the component’s
DOM is updated to reflect its new state, in some cases without a roundtrip to the
server. The component's role in this process is fairly limited: it simply stores away the
new property value and then notifies the peer of the change. The peer contains the
logic for updating the DOM to reflect the new component state.
Not all property changes are handled through the peer on the
client side. Some property changes are propagated back to the server
and the component is rerendered using PPR.

Note:

Most property values that are set on the client result in automatic synchronization
with the server (although some complex Java objects are not sent to the client at all).
There are however, two types of properties that act differently: secured properties and
disconnected properties.
Secured properties are those that cannot be set on the client at all. For example, say a
malicious client used JavaScript to set the immediate flag on a commandLink
component to true. That change would then be propagated to the server, resulting in
server-side validation being skipped, causing a possible security hole (for more
information about using the immediate property, see Section 5.2, "Using the
Immediate Attribute"). Consequently, the immediate property is a secured property.
Attempts to set secured property from JavaScript will fail. For more information, see
Section 4.6.3, "How to Unsecure the disabled Property." Table 4–1 shows the secure
properties on the client components.
Table 4–1

Secure Client Properties

Component

Secure Property

AdfRichChooseColor

colorData

AdfRichComboboxListOfValue

disabled
readOnly

AdfRichCommandButton

disabled
readOnly
blocking

AdfRichCommandImageLink

blocking
disabled
partialSubmit

AdfRichCommandLink

readOnly

AdfRichDialog

dialogListener

AdfRichDocument

failedConnectionText

AdfRichInputColor

disabled
readOnly
colorData

AdfRichInputDate

disabled
readOnly
valuePassThru

AdfRichInputFile

disabled
readOnly

4-10 Web User Interface Developer's Guide for Oracle Application Development Framework

Accessing Component Properties on the Client

Table 4–1 (Cont.) Secure Client Properties
Component

Secure Property

AdfRichInputListOfValues

disabled
readOnly

AdfRichInputNumberSlider

disabled
readOnly

AdfRichInputNumberSplinBox

disabled
readOnly
maximum
minimum
stepSize

AdfRichInputRangeSlider

disabled
readOnly

AdfRichInputText

disabled
readOnly
secret

AdfRichPopUp

launchPopupListener
model
returnPopupListener
returnPopupDataListener
createPopupId

AdfRichUIQuery

conjunctionReadOnly
model
queryListener
queryOperationListener

AdfRichSelectBooleanCheckbox

disabled
readOnly

AdfRichSelectBooleanRadio

disabled
readOnly

AdfRichSelectManyCheckbox

disabled
readOnly
valuePassThru

AdfRichSelectManyChoice

disabled
readOnly
valuePassThru

AdfRichSelectManyListBox

disabled
readOnly
valuePassThru

AdfRichSelectManyShuttle

disabled
readOnly
valuePassThru

Using ADF Faces Client-Side Architecture 4-11

Accessing Component Properties on the Client

Table 4–1 (Cont.) Secure Client Properties
Component

Secure Property

AdfRichSelectOneChoice

disabled
readOnly
valuePassThru

AdfRichSelectOneListBox

disabled
readOnly
valuePassThru

AdfRichSelectOneRadio

disabled
readOnly
valuePassThru

AdfRichSelectOrderShuttle

disabled
readOnly
valuePassThru

AdfRichUITable

filterModel

AdfRichTextEditor

disabled
readOnly

AdfUIChart

chartDrillDownListener

AdfUIColumn

sortProperty

AdfUICommand

actionExpression
returnListener
launchListener
immediate

AdfUIComponentRef

componentType

AdfUIEditableValueBase

immediate
valid
required
localValueSet
submittedValue
requiredMessageDetail

AdfUIMessage.js

for

AdfUINavigationLevel

level

AdfUINavigationTree

rowDisclosureListener
startLevel
immediate

AdfUIPage

rowDisclosureListener
immediate

AdfUIPoll

immediate
pollListener

AdfUIProgress

immediate

AdfUISelectBoolean

selected

4-12 Web User Interface Developer's Guide for Oracle Application Development Framework

Accessing Component Properties on the Client

Table 4–1 (Cont.) Secure Client Properties
Component

Secure Property

AdfUISelectInput

actionExpression
returnListener

AdfUISelectRange

immediate
rangeChangeListener

AdfUIShowDetailBase

immediate
disclosureListener

AdfUISingleStep

selectedStep
maxStep

AdfUISubform

default

AdfUITableBase

rowDisclosureListener
selectionListener
immediate
sortListener
rangeChangeListener
showAll

AdfUITreeBase

immediate
rowDisclosureListener
selectionListener
focusRowKey
focusListener

AdfUITreeTable

rowsByDepth
rangeChangeListener

AdfUIValueBase

converter

ADF Faces does allow you to configure the disabled property so that it can be made
unsecure. This can be useful when you need to use JavaScript to enable and disable
buttons.
Disconnected properties are those that can be set on the client, but that do not propagate
back to the server. These properties have a lifecycle on the client that is independent of
the lifecycle on the server. For example, client form input components (like
AdfRichInputText) have a submittedValue property, just as the Java
EditableValueHolder components do. However, setting this property does not
directly affect the server. In this case, standard form submission techniques handle
updating the submitted value on the server.
A property can be both disconnected and secured. In practice, such properties act like
disconnected properties on the client: they can be set on the client, but will not be sent
to the server. But they act like secured properties on the server, in that they will refuse
any client attempts to set them.

4.6.1 How to Set Property Values on the Client
The ADF Faces framework provides setXYZ convenience functions that call through
to the underlying ADFUIComponent.setProperty function, passing the
appropriate property name (for more information, see the ADF Faces JavaScript

Using ADF Faces Client-Side Architecture 4-13

Accessing Component Properties on the Client

JavaDoc). Example 4–9 shows how you might use the setProperty function to set
the backgroundcolor property on an inputText component to red when the value
changes.
Example 4–9


function color(event) {
var inputComponent = event.getSource();
inputComponent.setproperty("inlineStyle", "background-color:Red");
}






By using these functions, you can change the value of a property, and as long as it is
not a disconnected property or a secure property, the value will also be changed on the
server.

4.6.2 What You May Need to Know About Setting Properties on the Client
There may be cases when you do not want the value of the property to always be
delivered and synchronized to the server. For example, say you have inputText
components in a form, and as soon as a user changes a value in one of the components,
you want the changed indicator to display. To do this, you might use JavaScript to set
the changed attribute to true on the client component when the
valueChangeEvent event is delivered. Say also, you do not want the changed
indicator to display once the user submits the page, because at that time, the values are
saved.
Say you use JavaScript to set the changed attribute to true when the
valueChangeEvent is delivered, as shown in
Example 4–10

Using JavaScript to Set the changed Property



function changed(event) {
var inputComponent = event.getSource();
inputComponent.setChanged(true);
}







Using this example, the value of the changed attribute, which is true, will also be
sent to the server, because all the properties on the component are normally
synchronized to the server. So the changed indicator will continue to display.
To make it so the indicator does not display when the values are saved to the server,
you might use one of the following alternatives:

4-14 Web User Interface Developer's Guide for Oracle Application Development Framework

Accessing Component Properties on the Client

■

Move the logic from the client to the server, using an event listener. Use this
alternative when there is an event being delivered to the server, such as the
valueChangeEvent event. Example 4–11 shows example JSP code.

Example 4–11

JSP Code for Setting Property Values on the Server






Example 4–12 shows the corresponding managed bean code.
Example 4–12

Using a Managed Bean to Set a Property Value

import javax.faces.event.ValueChangeEvent;
import oracle.adf.view.rich.context.AdfFacesContext;
public class TestBean {
public TestBean() {}
public void valueChange(ValueChangeEvent valueChangeEvent)
{
setChanged(true);
AdfFacesContext adfFacesContext = AdfFacesContext.getCurrentInstance();
adfFacesContext.addPartialTarget(valueChangeEvent.getComponent());
FacesContext.getCurrentInstance().renderResponse();
}
public void setChanged(boolean changed)
{
_changed = changed;
}
public boolean isChanged()
{
return _changed;
}
private boolean _changed;
}
■

Move the logic to the server, using JavaScript that invokes a custom server event
and a serverListener tag. Use this when there is no event being delivered.
Example 4–13 shows the JSP code.

Example 4–13
Listener

JSP Code for Setting Property Values Using JavaScript and a Server



function changed(event)
{
var inputComponent = event.getSource();
AdfCustomEvent.queue(inputComponent, "myCustomEvent", null, true);
}








Example 4–14 shows the managed bean code.
Example 4–14

Using a Custom Event to Set a Property Value

package test;
import javax.faces.context.FacesContext;
import oracle.adf.view.rich.context.AdfFacesContext;
import oracle.adf.view.rich.render.ClientEvent;
public class Test2Bean
{
public Test2Bean()
{
}
public void doCustomEvent(ClientEvent event)
{
setChanged(true);
AdfFacesContext adfFacesContext = AdfFacesContext.getCurrentInstance();
adfFacesContext.addPartialTarget(event.getComponent());
FacesContext.getCurrentInstance().renderResponse();
}
public void setChanged(boolean changed)
{
_changed = changed;
}
public boolean isChanged()
{
return _changed;
}
private boolean _changed;
}
■

On the client component, set the changed attribute to true, which will propagate
to the server, but then use an actionListener on the command component to
set the changed attribute back to false. Example 4–15 shows the JSP code.

Example 4–15 JSP Code for Using a Listener on a Command Component to Set a
Property Value


function changed(event) {
var inputComponent = event.getSource();
inputComponent.setChanged(true);
}





4-16 Web User Interface Developer's Guide for Oracle Application Development Framework

Accessing Component Properties on the Client




Example 4–16 shows the corresponding managed bean code.
Example 4–16

Using an ActionLIstener to Set a Property Value

package test;
import javax.faces.event.ActionEvent;
import oracle.adf.view.rich.component.rich.input.RichInputText;
public class Test3Bean
{
public Test3Bean()
{
}
public void clear(ActionEvent actionEvent)
{
_input.setChanged(false);
}
public void setInput(RichInputText input)
{
_input = input;
}
public RichInputText getInput()
{
return _input;
}
private RichInputText _input;
}

4.6.3 How to Unsecure the disabled Property
You use the unsecured property to set the disabled property to be unsecure. You
need to manually add this property and the value of disabled to the code for the
component whose disabled property should be unsecure. For example, the code for
a button whose disabled property should be unsecured would be:


Once you set the unsecure attribute to disabled, a malicious JavaScript could
change the disabled attribute unwittingly. For example, say you have an expense
approval page, and on that page, you want certain managers to be able to only
approve invoices that are under $200. For this reason, you want the approval button to
be disabled unless the current user is allowed to approve the invoice.
If you did not set the unsecured attribute to disabled, the approval button would
remain disabled until a round-trip to the server occurs, where logic determines if the
current user can approve the expense. But because you want the button to display
correctly as the page loads the expense, say you set the unsecure attribute to
disabled. Now you can use JavaScript on the client to determine if the button should
be disabled. But now, any JavaScript (including malicious JavaScript that you have no
control over) can do the same thing.

Using ADF Faces Client-Side Architecture 4-17

Using Bonus Attributes for Client-Side Components

To avoid the malicious JavaScript, the application has to always assume that the
button may have been enabled by malicious client side Javascript and therefore needs
to always recheck that the current manager has the appropriate spending authority
before performing the approval. In the expense report approval screen, you might
have JavaScript that checks that the amount is under $200, but you still need to have
the action for the approval button perform the logic on the server. Adding the logic to
the server ensures that the disabled attribute does not get changed when it should not.
Similarly, if you allow your application to be modified at runtime, and you allow users
to potentially edit the unsecure and/or the disabled attributes, you must ensure
that your application still performs the same logic as if the round-trip to the server had
occurred.

4.6.4 What Happens at Runtime: How Client Properties Are Set on the Client
Calling the setProperty() function on the client sets the property to the new value,
and synchronously fires a PropertyChangeEvent event with the old and new
values (as long as the value is different). Also, setting a property may cause the
component to rerender itself.

4.7 Using Bonus Attributes for Client-Side Components
In some cases you may want to send additional information to the client beyond the
built-in properties. This can be accomplished using bonus attributes. Bonus attributes
are extra attributes that you can add to a component using the clientAttribute
tag. For performance reasons, the only bonus attributes sent to the client are those
specified by clientAttribute.
The clientAttribute tag specifies a name/value pair that is added to the
server-side component's attribute map. In addition to populating the server-side
attribute map, using the clientAttribute tag results in the bonus attribute being
sent to the client, where it can be accessed through the
AdfUIComponent.getProperty("bonusAttributeName") method.
The framework takes care of marshalling the attribute value to the client. The
marshalling layer supports marshalling of a range of object types, including strings,
booleans, numbers, dates, arrays, maps, and so on. For more information on
marshalling, see Section 6.4.3, "What You May Need to Know About Marshalling and
Unmarshalling Data."
Performance Tip: In order to avoid excessive marshalling overhead,
use client-side bonus attributes sparingly.

Note: The clientAttribute tag should be used only for bonus
(application-defined) attributes. If you need access to standard
component attributes on the client, instead of using the
clientAttribute tag, simply set the clientComponent attribute
to true. For more information, see Section 4.4, "Instantiating
Client-Side Components."

4.7.1 How to Create Bonus Attributes
You can use the Component Palette to add a bonus attribute to a component.

4-18 Web User Interface Developer's Guide for Oracle Application Development Framework

Understanding Rendering and Visibility

Before you begin
It may be helpful to have an understanding of bonus attributes. For more information,
see Section 4.7, "Using Bonus Attributes for Client-Side Components."
To create bonus attributes:
1. In the Structure window, select the component to which you would like to add a
bonus attribute.
2.

In the Component Palette, from the Operations panel, drag and drop a Client
Attribute as a child to the component.

3.

In the Property Inspector, set the Name and Value attributes.

4.7.2 What You May Need to Know About Marshalling Bonus Attributes
Although client-side bonus attributes are automatically delivered from the server to
the client, the reverse is not true. That is, changing or setting a bonus attribute on the
client will have no effect on the server. Only known (nonbonus) attributes are
synchronized from the client to the server. If you want to send application-defined
data back to the server, you should create a custom event. For more information, see
Section 6.4, "Sending Custom Events from the Client to the Server."

4.8 Understanding Rendering and Visibility
All ADF Faces display components have two attributes that relate to whether or not
the component is displayed on the page for the user to see: rendered and visible.
The rendered attribute has very strict semantics. When rendered is set to false,
there is no way to show a component on the client without a roundtrip to the server.
To support dynamically hiding and showing page contents, the framework adds the
visible attribute. When set to false, the component's markup is available on the
client but the component is not displayed. Therefore calls to the setVisible(true)
or setVisible(false) method will, respectively, show and hide the component
within the browser (as long as rendered is set to true), whether those calls happen
from Java or from JavaScript. However, because visible simply shows and hides the
content in the DOM, it doesn't always provide the same visual changes as using the
rendered would.
You should set the visible attribute to false
only when you absolutely need to be able to toggle visibility without a
roundtrip to the server, for example in JavaScript. Nonvisible
components still go through the component lifecycle, including
validation.

Performance Tip:

If you do not need to toggle visibility only on the client, then you
should instead set the rendered attribute to false. Making a
component not rendered (instead of not visible) will improve server
performance and client response time because the component will not
have client-side representation, and will not go through the
component lifecycle.
Example 4–17 shows two outputText components, only one of which is rendered at
a time. The first outputText component is rendered when no value has been entered
into the inputText component. The second outputText component is rendered
when a value is entered.

Using ADF Faces Client-Side Architecture 4-19

Understanding Rendering and Visibility

Example 4–17

Rendered and Not Rendered Components











Provided a component is rendered in the client, you can either display or hide the
component on the page using the visible property.
Example 4–18 shows how you might achieve the same functionality as shown in
Example 4–17, but in this example, the visible attribute is used to determine which
component is displayed (the rendered attribute is true by default, it does not need
to be explicitly set).
Example 4–18

Visible and Not Visible Components











However, because using the rendered attribute instead of the visible attribute
improves performance on the server side, you may instead decide to have JavaScript
handle the visibility.
Example 4–19 shows the page code for JavaScript that handles the visiblity of the
components.
Example 4–19

Using JavaScript to Turn On Visibility

function showText()
{
var output1 = AdfUIComponent.findComponent("output1")
var output2 = AdfUIComponent.findComponent("output2")
var input = AdfUIComponent.findComponent("input")
if (input.getValue() == "")
{
output1.setVisible(true);
}
else
{
output2.setVisible(true)
}

4-20 Web User Interface Developer's Guide for Oracle Application Development Framework

Understanding Rendering and Visibility

}

4.8.1 How to Set Visibility Using JavaScript
You can create a conditional JavaScript function that can toggle the visible attribute
of components.
Before you begin
It may be helpful to have an understanding of how components are displayed. For
more information, see Section 4.8, "Understanding Rendering and Visibility."
To set visibility:
1. Create the JavaScript that can toggle the visibility. Example 4–19 shows a script
that turns visibility on for one outputText component if there is no value;
otherwise, the script turns visibility on for the other outputText component.
2.

For each component that will be needed in the JavaScript function, expand the
Advanced section of the Property Inspector and set the ClientComponent
attribute to true. This creates a client component that will be used by the
JavaScript.

3.

For the components whose visibility will be toggled, set the visible attribute to
false.

Example 4–20 shows the full page code used to toggle visibility with JavaScript.
Example 4–20

JavaScript Toggles Visibility



function showText()
{
var output1 = AdfUIComponent.findComponent("output1")
var output2 = AdfUIComponent.findComponent("output2")
var input = AdfUIComponent.findComponent("input")
if (input.value == "")
{
output1.setVisible(true);
}
else
{
output2.setVisible(true)
}
}










Using ADF Faces Client-Side Architecture 4-21

JavaScript Library Partitioning










4.8.2 What You May Need to Know About Visible and the isShowing Function
If the parent of a component has its visible attribute set to false, when the
isVisible function is run against a child component whose visible attribute is set
to true, it will return true, even though that child is not displayed. For example, say
you have a panelGroupLayout component that contains an outputText
component as a child, and the panelGroupLayout component’s visible attribute
is set to false, while the outputText component’s visible attribute is left as the
default (true). On the client, neither the panelGroupLayout nor the outputText
component will be displayed, but if the isVisible function is run against the
outputText component, it will return true.
For this reason, the framework provides the isShowing() function. This function
will return false if the component’s visible attribute is set to false, or if any
parent of that component has visible set to false.

4.9 JavaScript Library Partitioning
A common issue with JavaScript-heavy frameworks is determining how best to
deliver a large JavaScript code base to the client. On one extreme, bundling all code
into a single JavaScript library can result in a long download time. On the other
extreme, breaking up JavaScript code into many small JavaScript libraries can result in
a large number of roundtrips. Both approaches can result in the end user waiting
unnecessarily long for the initial page to load.
To help mitigate this issue, ADF Faces aggregates its JavaScript code into partitions. A
JavaScript library partition contains code for components and/or features that are
commonly used together. By default, ADF Faces provides a partitioning that is
intended to provide a balance between total download size and total number of
roundtrips.
One benefit of ADF Faces's library partitioning strategy is that it is configurable.
Because different applications make use of different components and features, the
default partitioning provided by ADF Faces may not be ideal for all applications. As
such, ADF Faces allows the JavaScript library partitioning to be customized on a
per-application basis. This partitioning allows application developers to tune the
JavaScript library footprint to meet the needs of their application.
ADF Faces groups its components’ JavaScript files into JavaScript features. A
JavaScript feature is a collection of JavaScript files associated with a logical identifier
that describes the feature. For example, the panelStretchLayout client component
is comprised of the following two JavaScript files
■

oracle/adf/view/js/component/rich/layout/
AdfRichPanelStretchLayout.js

4-22 Web User Interface Developer's Guide for Oracle Application Development Framework

JavaScript Library Partitioning

■

oracle/adfinternal/view/js/laf/dhtml/rich/
AdfDhtmlPanelStretchLayoutPeer.js

These two files are grouped into the AdfRichPanelStretchLayout feature.
JavaScript features are further grouped into JavaScript partitions. JavaScript partitions
allow you to group JavaScript features into larger collections with the goal of
influencing the download size and number of round trips. For example, since the
panelStretchLayout component is often used with the panelSplitter
component, the features for these two components are grouped together in the stretch
partition, along with the other ADF Faces layout components that can stretch their
children. At runtime, when a page is loaded, the framework determines the
components used on the page, and then from that, determines which features are
needed (feature names are the same as the components’ constructor name). Only the
partitions that contain those features are downloaded.
Features and partitions are defined using configuration files. ADF Faces ships with a
default features and partitions configuration file. You can overwrite the default
partitions file by creating your own implementation. When you create custom ADF
Faces components, you can create your own features and partition configuration files
for those components.
By default, JavaScript partitioning is turned on. Whether or not your application uses
JavaScript partitioning is determined by a context parameter in the web.xml file. For
more information, see Section A.2.3.17, "JavaScript Partitioning."

4.9.1 How to Create a JavaScript Feature
You create a JavaScript feature by creating an adf-js-features.xml file, and
then adding entries for the features.
You create JavaScript features when you create custom ADF
Faces components. All existing ADF Faces components already have
features created for them, and these cannot be changed.

Note:

Before you begin
It may be helpful to have an understanding of JavaScript partitioning works. For more
information, see Section 4.9, "JavaScript Library Partitioning."
To create a JavaScript feature:
1. If not already created, create a META-INF directory for your component.
2.

Right-click the META-INF directory, and choose New from the context menu.

3.

In the New Gallery, expand General, select XML and then XML Document, and
click OK.
Tip: If you don’t see the General node, click the All Technologies
tab at the top of the Gallery.

4.

Enter adf-js-features.xml as the file name and save it in the META-INF
directory.

5.

In the source editor, replace the generated code with the code shown in
Example 4–21.

Using ADF Faces Client-Side Architecture 4-23

JavaScript Library Partitioning

Example 4–21

XML for adf-js-features.xml File




6.

Add the following elements to populate a feature with the relevant component
files and dependencies.
■
■

■

■

■

features: The root element of the configuration file.
feature: Create as a child to the features element. This element must
contain one feature-name child element and can also contain any number
of feature-class, as well as any number of feature-dependency
elements.
feature-name: Create as a child to the feature element. Specifies the name
of the feature. You must use the client component’s constructor name for this
value.
feature-class: Create as a child to the feature element. Specifies the
location of the single JavaScript file or class to be included in this feature.
There can be multiple feature-class elements.
feature-dependency: Create as a child to the feature element. Specifies
the name of another feature that this feature depends on. For example, if one
component B extends component A, then the feature that represents
component A must be listed as a dependency for component B. By noting
dependencies, the framework can ensure that any dependent classes are
available, even if the two features are not in the same partition.

Example 4–22 shows the feature element for a fictitious custom component that
uses popup components (and therefore has a dependency to the popup feature).
Example 4–22

JavaScript Features Configuration



AcmeMyPane

oracle/adfdemo/acme/js/component/AcmeMyPane.js


oracle/adfdemo/acme/js/event/AcmePaneSelectEvent.js


oracle/adfdemo/acme/js/component/AcmeMyPanePeer.js



AdfRichPopup


4.9.2 How to Create JavaScript Partitions
You create a JavaScript partition by creating an adf-js-partitions.xml file,
and then adding entries for the features.

4-24 Web User Interface Developer's Guide for Oracle Application Development Framework

JavaScript Library Partitioning

ADF Faces provides a default adf-js-partitions.xml file
(see Section E.1.1, "The adf-js-partitions.xml File"). If you want to
change the partition configuration, you need to create your own
complete adf-js-partitions.xml file. At runtime, the framework
will search the WEB-INF directory for that file. If one is not found, it
will load the default partition file.

Note:

Before you begin
It may be helpful to have an understanding of JavaScript partitioning works. For more
information, see Section 4.9, "JavaScript Library Partitioning."
To create JavaScript partitions:
1. Right-click the WEB-INF directory, and choose New from the context menu.
2.

In the New Gallery, expand General, select XML and then XML Document, and
click OK.
Tip: If you don’t see the General node, click the All Technologies
tab at the top of the Gallery.

3.

Enter adf-js-partitions.xml as the file name and save it in the WEB-INF
directory.

4.

In the source editor, replace the generated code with the code shown in
Example 4–23.

Example 4–23

XML for adf-js-partitions.xml File




5.

Add the following elements to populate a partition with the relevant features.
■
■

■

■

partitions: The root element of the configuration file.
partition: Create as a child to the partitions element. This element must
contain one partition-name child element and one or more feature
elements.
partition-name: Create as a child to the partition element. Specifies the
name of the partition. This value will be used to produce a unique URL for
this partition’s JavaScript library.
feature: Create as a child to the partition element. Specifies the feature to
be included in this partition. There can be multiple feature elements.
Any feature configured in the adf-js-features.xml file
that does not appear in a partition is treated as if it were in its own
partition.

Tip:

Example 4–24 shows the partition element for the tree partition that contains
the AdfRichTree and AdfRichTreeTable features.

Using ADF Faces Client-Side Architecture 4-25

JavaScript Library Partitioning

Example 4–24

JavaScript Partition Configuration


tree
AdfUITree
AdfUITreeTable
AdfRichTree
AdfRichTreeTable


4.9.3 What Happens at Runtime: JavaScript Partitioning
ADF Faces loads the library partitioning configuration files at application initialization
time. First, ADF Faces searches for all adf-js-features.xml files in the META-INF
directory and loads all that are found (including the ADF Faces default feature
configuration file).
For the partition configuration file, ADF Faces looks for a single file named
adf-js-partitions.xml in the WEB-INF directory. If no such file is found, the
ADF Faces default partition configuration is used.
During the render traversal, ADF Faces collects information about which JavaScript
features are required by the page. At the end of the traversal, the complete set of
JavaScript features required by the (rendered) page contents is known. Once the set of
required JavaScript features is known, ADF Faces uses the partition configuration file
to map this set of features to the set of required partitions. Given the set of required
partitions, the HTML 

Adding Drag and Drop Functionality 33-9

Adding Drag and Drop Functionality for Collections

33.4 Adding Drag and Drop Functionality for Collections
You use the collectionDropTarget and dragSource tags to add drag and drop
functionality that allows users to drag an item from one collection (for example, a row
from a table), and drop it into another collection component such, as a tree. For
example, in the File Explorer application, users can drag a file from the table that
displays directory contents to any folder in the directory tree. Figure 33–3 shows the
File0.doc object being dragged from the table displaying the contents of the
Folder0 directory to the Folder3 directory. Once the drop is complete, the object
will become part of the collection that makes up Folder3.
Figure 33–3 Drag and Drop Functionality in the File Explorer Application

As with dragging and dropping single objects, you can have a drop on a collection
with a copy, move, or copy and paste as a link (or a combination of the three), and use
dataFlavor tags to limit what a target will accept.
When the target source is a collection and it supports the move operation, you may
also want to also implement a method for the dragDropEndListener attribute,
which is referenced from the source component and is used to clean up the collection
after the drag and drop operation. For more information, see Section 33.4.2, "What You
May Need to Know About the dragDropEndListener".

33.4.1 How to Add Drag and Drop Functionality for Collections
To add drag and drop functionality for collections, instead of using the dropTarget
tag, you use the collectionDropTarget tag. You then must implement the event
handler method that will handle the logic for the drag and drop action. Next, you
define the source for the drag and drop operation using the dragSource tag.
Before you begin:
It may be helpful to have an understanding of drag and drop functionality. For more
information, see Section 33.4, "Adding Drag and Drop Functionality for Collections."
You may also find it helpful to understand functionality that can be added using other
ADF Faces features. For more information, see Section 33.1.1, "Additional
Functionality for Drag and Drop."
You will need to complete this task:
Create the source and target components on the page.

33-10 Web User Interface Developer's Guide for Oracle Application Development Framework

Adding Drag and Drop Functionality for Collections

To add drag and drop functionality:
1. Add a collectionDropTarget tag as a child to the target collection component
by dragging a Collection Drop Target from the Component Palette.
2.

In the Insert Collection Drop Target dialog, enter an expression for the
dropListener attribute that evaluates to a method on a managed bean that will
handle the event (you will create this code in Step 4).

3.

In the Property Inspector, set the following:
■

actions: Select the actions that can be performed on the source during the
drag and drop operation.
If no actions are specified, the default is COPY.

■

modelName: Define the model for the collection.
The value of the modelName attribute is a String object used to identify the
drag source for compatibility purposes. The value of this attribute must match
the value of the discriminant attribute of the dragSource tag you will use
in a Step 6. In other words, this is an arbitrary name and works when the
target and the source share the same modelName value or discriminant value.

4.

In the managed bean inserted into the EL expression in Step 2, implement the
handler for the drop event.
This method must take a DropEvent event as a parameter and return a
DnDAction. This method should use the DropEvent to get the Transferable
object and from there get the RowKeySet (the rows that were selected for the
drag). Using the CollectionModel obtained through the Transferable object,
the actual rowData can be obtained to complete the drop. The method should
then check the DropEvent to determine whether it will accept the drop or not. If
the method accepts the drop, it should perform the drop and return the
DnDAction it performed -- DnDAction.COPY, DnDAction.MOVE or
DnDAction.LINK, otherwise it should return DnDAction.NONE to indicate that
the drop was rejected.
Example 33–5 shows the event handler method on the CollectionDnd.java
managed bean used in the collectionDropTarget demo that handles the copy
of the row between two tables.

Example 33–5

Event Handler Code for a dropListener for a Collection

public DnDAction handleDrop(DropEvent dropEvent)
{
Transferable transferable = dropEvent.getTransferable();
// The data in the transferable is the row key for the dragged component.
DataFlavor rowKeySetFlavor =
DataFlavor.getDataFlavor(RowKeySet.class, "DnDDemoModel");
RowKeySet rowKeySet = transferable.getData(rowKeySetFlavor);
if (rowKeySet != null)
{
// Get the model for the dragged component.
CollectionModel dragModel = transferable.getData(CollectionModel.class);
if (dragModel != null)
{
// Set the row key for this model using the row key from the transferable.
Object currKey = rowKeySet.iterator().next();
dragModel.setRowKey(currKey);
// And now get the actual data from the dragged model.
// Note this won't work in a region.
Adding Drag and Drop Functionality

33-11

Adding Drag and Drop Functionality for Collections

DnDDemoData dnDDemoData = (DnDDemoData)dragModel.getRowData();
// Put the dragged data into the target model directly.
// Note that if you wanted validation/business rules on the drop,
// this would be different.
// getTargetValues() is the target collection used by the target component
getTargetValues().add(dnDDemoData);
}
return dropEvent.getProposedAction();
}
else
{
return DnDAction.NONE;
}
}
5.

In the Component Palette, from the Operations panel, drag and drop a Drag
Source as a child to the source component.

6.

With the dragSource tag selected, in the Property Inspector set the actions,
discriminant, and any dragDropEndListener as configured for the target.
For instance, the dragSource tag may appear similar to the following:


33.4.2 What You May Need to Know About the dragDropEndListener
There may be cases when after a drop event, you have to clean up the source
collection. For example, if the drag caused a move, you may have to clean up the
source component so that the moved item is no longer part of the collection.
The dragSource tag contains the dragDropEndListener attribute that allows you
to register a handler that contains logic for after the drag drop operation ends.
For example, if you allow a drag and drop to move an object, you may have to
physically remove the object from the source component once you know the drop
succeeded. Example 33–6 shows a handler for a dragDropEndListener. attribute
Example 33–6

Handler for dragDropEndListener

public void endListener(DropEvent dropEvent)
{
Transferable transferable = dropEvent.getTransferable();
// The data in the transferrable is the row key for the dragged component.
DataFlavor rowKeySetFlavor =
DataFlavor.getDataFlavor(RowKeySet.class, "DnDDemoModel");
RowKeySet rowKeySet = transferable.getData(rowKeySetFlavor);
if (rowKeySet != null)
{
Integer currKey = (Integer)rowKeySet.iterator().next();
// Remove the dragged data from the source model directly.
// getSourceValues() represents a collection object used by the source
// component
Object removed = getSourceValues().remove(currKey.intValue());
}
// Need to add the drag source table so it gets redrawn.
// The drag source component needs to be partially refreshed explicitly, while
// drop target component automatically refreshed and displayed.

33-12 Web User Interface Developer's Guide for Oracle Application Development Framework

Adding Drag and Drop Functionality for Components

AdfFacesContext.getCurrentInstance().addPartialTarget(dropEvent.getDragComponent()
);

33.5 Adding Drag and Drop Functionality for Components
You can allow components to be moved from one parent to another, or you can allow
child components of a parent component to be reordered. For example, Figure 33–4
shows the darker panelBox component being moved from being the first child
component of the panelGrid component to the last.
Figure 33–4 Drag and Drop Functionality Between Components

If you want to move components into or out of a
panelDashboard component, then you need to use procedures specific
to that component. For more information, see Section 33.6, "Adding
Drag and Drop Functionality Into and Out of a panelDashboard
Component."

Note:

33.5.1 How to Add Drag and Drop Functionality for Components
Adding drag and drop functionality for components is similar for objects. However,
instead of using the attributeDragSource tag, use the componentDragSource
tag. As with dragging and dropping objects or collections, you also must implement a
dropListener handler.

Adding Drag and Drop Functionality

33-13

Adding Drag and Drop Functionality for Components

Before you begin:
It may be helpful to have an understanding of drag and drop functionality. For more
information, see Section 33.5, "Adding Drag and Drop Functionality for Components."
You may also find it helpful to understand functionality that can be added using other
ADF Faces features. For more information, see Section 33.1.1, "Additional
Functionality for Drag and Drop."
To add drag and drop functionality:
1. From the Operations panel of the Component Palette, drag and drop a Drop
Target as a child to the target component.
2.

In the Insert Drop Target dialog, enter an expression that evaluates to a method on
a managed bean that will handle the event (you will create this code in Step 4).

3.

With the dropTarget tag still selected, in the Property Inspector, select a valid
action set for the actions attribute.

4.

In the managed bean referenced in the EL expression created in Step 2 for the
dropListener attribute, create the event handler method (using the same name
as in the EL expression) that will handle the drag and drop functionality.
If the method accepts the drop, it should perform the drop and return the
DnDAction it performed -- DnDAction.COPY, DnDAction.MOVE or
DnDAction.LINK, otherwise it should return DnDAction.NONE to indicate that
the drop was rejected
This handler method should use the DropEvent event to get the transferable
object and its data and then complete the move or copy, and reorder the
components as needed. Once the method completes the drop, it should return the
DnDAction it performed. Otherwise, it should return DnDAction.NONE to
indicate that the drop was rejected.
Example 33–7 shows the handleComponentMove event handler on the
DemoDropHandler.java managed bean used by the componentDragSource
JSF page in the demo application.

Example 33–7

Event Handler Code for a dropListener That Handles a Component Move

public DnDAction handleComponentMove(DropEvent dropEvent)
{
Transferable dropTransferable = dropEvent.getTransferable();
UIComponent movedComponent = dropTransferable.getData
(DataFlavor.UICOMPONENT_FLAVOR);
if ((movedComponent != null) &&
DnDAction.MOVE.equals(dropEvent.getProposedAction()))
{
UIComponent dropComponent = dropEvent.getDropComponent();
UIComponent dropParent = dropComponent.getParent();
UIComponent movedParent = movedComponent.getParent();
UIComponent rootParent = null;
ComponentChange change = null;
// Build the new list of IDs, placing the moved component after the dropped
//component.
String movedLayoutId = movedParent.getId();
String dropLayoutId = dropComponent.getId();
List reorderedIdList = new
ArrayList(dropParent.getChildCount());

33-14 Web User Interface Developer's Guide for Oracle Application Development Framework

Adding Drag and Drop Functionality Into and Out of a panelDashboard Component

for (UIComponent currChild : dropParent.getChildren())
{
String currId = currChild.getId();
if (!currId.equals(movedLayoutId))
{
reorderedIdList.add(currId);
if (currId.equals(dropLayoutId))
{
reorderedIdList.add(movedLayoutId);
}
}
}
change = new ReorderChildrenComponentChange(reorderedIdList);
rootParent = dropParent;
// apply the change to the component tree immediately
// change.changeComponent(rootParent);
// redraw the shared parent
AdfFacesContext.getCurrentInstance().addPartialTarget(rootParent);
return DnDAction.MOVE;
}
else
{
return DnDAction.NONE;
}
}
5.

Add a componentDragSource tag to the source component by dragging and
dropping a Component Drag Source from the Component Palette as a child of the
source component. For instance, the componentDragSource tag may appear
similar to the following:


33.6 Adding Drag and Drop Functionality Into and Out of a
panelDashboard Component
By default the panelDashboard component supports dragging and dropping
components within itself. That is, you can reorder components in a panelDashboard
component without needing to implement a listener or use additional tags. However,
if you want to be able to drag a component into a panelDashboard component, or to
drag a component out of a panelDashboard component, you do need to use tags
and implement a listener. Because you would be dragging and dropping a component,
you use the componentDragSource tag when dragging into the panelDashboard.
However, because the panelDashboard already supports being a drop target, you do
not need to use the dropTarget tag. Instead, you need to use a dataFlavor tag with
a discriminant. The tag and discriminant notify the framework that the drop is from an
external component.
Dragging a component out of a panelDashboard is mostly the same as dragging and
dropping any other component. You use a dropTarget tag for the target and the
componentDragSource tag for the source. However, you must also use the
dataFlavor tag and a discriminant.

Adding Drag and Drop Functionality

33-15

Adding Drag and Drop Functionality Into and Out of a panelDashboard Component

33.6.1 How to Add Drag and Drop Functionality Into a panelDashboard Component
Because the panelDashboard component has built-in drag and drop functionality
used to reorder panelBox components within the dashboard, you need not use a
dropTarget tag, but you do need to use a dataFlavor tag with a discriminant and
implement the dropListener. In that implementation, you need to handle the
reorder of the components.
Before you begin:
It may be helpful to have an understanding of drag and drop functionality. For more
information, see Section 33.6, "Adding Drag and Drop Functionality Into and Out of a
panelDashboard Component."
You may also find it helpful to understand functionality that can be added using other
ADF Faces features. For more information, see Section 33.1.1, "Additional
Functionality for Drag and Drop."
Before you begin:
1. Create a panelDashboard component. For more information, see Section 9.7,
"Arranging Contents in a Dashboard."
2.

Create another component outside of the panelDashboard that contains
panelBox components. For more information about panelBox components, see
Section 9.8.3, "How to Use the panelBox Component."

To add drag and drop functionality into a panelDashboard component:
In the Structure window, select the panelDashboard component that is to be the
target component.

1.
2.

In the Property Inspector, for DropListener, enter an expression that evaluates to a
method on a managed bean that will handle the drop event (you will create this
code in Step 6).

3.

In the Component Palette, from the Operations panel, drag a Data Flavor and
drop it as a child to the panelDashboard component.

4.

In the Insert Data Flavor dialog, enter
javax.faces.component.UIComponent.

5.

In the Property Inspector, set Discriminant to a unique name that will identify the
components allowed to be dragged into the panelDashboard component, for
example, dragIntoDashboard.

6.

In the managed bean referenced in the EL expression created in Step 2 for the
dropListener attribute, create the event handler method (using the same name
as in the EL expression) that will handle the drag and drop functionality.
This method must take a DropEvent event as a parameter and return a
DnDAction of NONE, because the panelDashboard handles the positioning of its
child components.
This handler method should use the
dropEvent.getTransferable().getData(DataFlavor.UICOMPONENT_
FLAVOR) to get the transferable object and its data. Once the method
completes the drop, you can use the
org.apache.myfaces.trinidad.change.ReorderChildrenComponent
Change method to preserve the new ordering of the children and the
dropEvent.getDropSiteIndex() method to get the location at which the user
wants the dragged component. You can also use the

33-16 Web User Interface Developer's Guide for Oracle Application Development Framework

Adding Drag and Drop Functionality Into and Out of a panelDashboard Component

dashboardComponent.prepareOptimizedEncodingOfInsertedChild()
method to animate the drop of the component.
Example 33–8 shows the move event handler and helper methods on the
DemoDashboardBean.java managed bean used by the dashboard JSF page in
the ADF Faces demo application.
Example 33–8

Handler for DropListener on a panelDashboard Component

public DnDAction move(DropEvent e)
{
UIComponent dropComponent = e.getDropComponent();
UIComponent movedComponent = e.getTransferable().getData(DataFlavor.UICOMPONENT_FLAVOR);
UIComponent movedParent = movedComponent.getParent();
// Ensure that we are handling the re-order of a direct child of the panelDashboard:
if (movedParent.equals(dropComponent) && dropComponent.equals(_dashboard))
{
// Move the already rendered child and redraw the side bar since the insert indexes have
// changed:
_moveDashboardChild(e.getDropSiteIndex(), movedComponent.getId());
}
else
{
// This isn't a re-order but rather the user dropped a minimized side bar item into the
// dashboard, in which case that item should be restored at the specified drop location.
String panelKey = _getAssociatedPanelKey(movedComponent);
if (panelKey != null)
{
UIComponent panelBoxToShow = _dashboard.findComponent(panelKey);
// Make this panelBox rendered:
panelBoxToShow.setRendered(true);
int insertIndex = e.getDropSiteIndex();
// Move the already rendered child and redraw the side bar since the insert indexes have
// changed and because the side bar minimized states are out of date:
_moveDashboardChild(insertIndex, panelKey);
// Let the dashboard know that only the one child should be encoded during the render phase:
_dashboard.prepareOptimizedEncodingOfInsertedChild(
FacesContext.getCurrentInstance(),
insertIndex);
}
}
return DnDAction.NONE; // the client is already updated, so no need to redraw it again
}
private void _moveDashboardChild(int dropIndex, String movedId)
{
// Build the new list of IDs, placing the moved component at the drop index.
List reorderedIdList = new ArrayList(_dashboard.getChildCount());
int index = 0;
boolean added = false;
for (UIComponent currChild : _dashboard.getChildren())
{
if (currChild.isRendered())
{
if (index == dropIndex)

Adding Drag and Drop Functionality

33-17

Adding Drag and Drop Functionality Into and Out of a panelDashboard Component

{
reorderedIdList.add(movedId);
added = true;
}
String currId = currChild.getId();
if (currId.equals(movedId) && index < dropIndex)
{
// component is moved later, need to shift the index by 1
dropIndex++;
}
if (!currId.equals(movedId))
{
reorderedIdList.add(currId);
}
index++;
}
}
if (!added)
{
// Added to the very end:
reorderedIdList.add(movedId);
}
// Apply the change to the component tree immediately:
ComponentChange change = new ReorderChildrenComponentChange(reorderedIdList);
change.changeComponent(_dashboard);
// Add the side bar as a partial target since we need to redraw the state of the side bar items
// since their insert indexes are changed and possibly because the side bar minimized states
// are out of date:
RequestContext rc = RequestContext.getCurrentInstance();
rc.addPartialTarget(_sideBarContainer);
}
7.

In the Component Palette, from the Operations panel, drag a Component Drag
Source and drop it as a child to the panelBox component that will be the source
component.

8.

In the Property Inspector, set Discriminant to be the same value as entered for the
Discriminant on the panelDashboard in Step 5.

33.6.2 How to Add Drag and Drop Functionality Out of a panelDashboard Component
Implementing drag and drop functionality out of a panelDashboard component is
similar to standard drag and drop functionality for other components, except that you
must use a dataFlavor tag with a discriminant.
Before you begin:
It may be helpful to have an understanding of drag and drop functionality. For more
information, see Section 33.6, "Adding Drag and Drop Functionality Into and Out of a
panelDashboard Component."
You may also find it helpful to understand functionality that can be added using other
ADF Faces features. For more information, see Section 33.1.1, "Additional
Functionality for Drag and Drop."

33-18 Web User Interface Developer's Guide for Oracle Application Development Framework

Adding Drag and Drop Functionality Into and Out of a panelDashboard Component

How to add drag and drop functionality out of a panelDashboard component:
1. In the Component Palette, from the Operations panel, drag and drop a Drop
Target as a child to the target component.
2.

In the Insert Drop Target dialog, enter an expression that evaluates to a method on
a managed bean that will handle the event (you will create this code in Step 5) and
enter javax.faces.component.UIComponent as the FlavorClass.

3.

With the dropTarget tag still selected, in the Property Inspector, select MOVE as
the value action attribute.

4.

In the Structure window, select the dataFlavor tag and in the Property Inspector,
set Discriminant to a unique name that will identify the panelBox components
allowed to be dragged into this component, for example, dragOutOfDashboard.

5.

In the managed bean referenced in the EL expression created in Step 2 for the
dropListener attribute, create the event handler method (using the same name
as in the EL expression) that will handle the drag and drop functionality.
This handler method should use the DropEvent event to get the transferable
object and its data and then complete the move and reorder the components as
needed. Once the method completes the drop, it should return a DnDAction of
NONE.
You can use the
dashboardComponent.prepareOptimizedEncodingOfDeletedChild()
method to animate the removal of the panelBox component.
Example 33–9 shows the handleSideBarDrop event handler and helper
methods on the oracle.adfdemo.view.layout.DemoDashboardBean.java
managed bean used by the dashboard JSF page in the demo application.

Example 33–9 Event Handler Code for a dropListener That Handles a panelBox Move Out of a panelDashboard Component
public DnDAction handleSideBarDrop(DropEvent e)
{
UIComponent movedComponent = e.getTransferable().getData(DataFlavor.UICOMPONENT_FLAVOR);
UIComponent movedParent = movedComponent.getParent();
// Ensure that the drag source is one of the items from the dashboard:
if (movedParent.equals(_dashboard))
{
_minimize(movedComponent);
}
return DnDAction.NONE; // the client is already updated, so no need to redraw it again
}
private void _minimize(UIComponent panelBoxToMinimize)
{
// Make this panelBox non-rendered:
panelBoxToMinimize.setRendered(false);
// If the dashboard is showing, let's perform an optimized render so the whole dashboard
doesn't
// have to be re-encoded.
// If the dashboard is hidden (because the panelBox is maximized), we will not do an optimized
// encode since we need to draw the whole thing.
if (_maximizedPanelKey == null)
{

Adding Drag and Drop Functionality

33-19

Adding Drag and Drop Functionality to a Calendar

int deleteIndex = 0;
List children = _dashboard.getChildren();
for (UIComponent child : children)
{
if (child.equals(panelBoxToMinimize))
{
_dashboard.prepareOptimizedEncodingOfDeletedChild(
FacesContext.getCurrentInstance(),
deleteIndex);
break;
}
if (child.isRendered())
{
// Only count rendered children since that's all that the panelDashboard can see:
deleteIndex++;
}
}
}
RequestContext rc = RequestContext.getCurrentInstance();
if (_maximizedPanelKey != null)
{
// Exit maximized mode:
_maximizedPanelKey = null;
_switcher.setFacetName("restored");
rc.addPartialTarget(_switcher);
}
// Redraw the side bar so that we can update the colors of the opened items:
rc.addPartialTarget(_sideBarContainer);
}
6.

In the Component Palette, from the Operations panel, drag and drop a
Component Drag Source as a child of the source panelBox component within
the panelDashboard component.

7.

In the Property Inspector, set Discriminant to be the same value as entered for the
Discriminant on the dataFlavor tag for the target component in Step 4.

33.7 Adding Drag and Drop Functionality to a Calendar
The calendar includes functionality that allows users to drag the handle of an activity
to change the end time. However, if you want users to be able to drag and drop an
activity to a different start time, or even a different day, then you implement drag and
drop functionality. Drag and drop allows you to not only move an activity, but also to
copy one.

33.7.1 How to Add Drag and Drop Functionality to a Calendar
You add drag and drop functionality by using the calendarDropTarget tag. Unlike
dragging and dropping a collection, there is no need for a source tag; the target (that is
the object to which the activity is being moved, in this case, the calendar) is responsible
for moving the activities. If the source (that is, the item to be moved or copied), is an
activity within the calendar, then you use only the calendarDropTarget tag. The tag
expects the transferable to be a CalendarActivity object.

33-20 Web User Interface Developer's Guide for Oracle Application Development Framework

Adding Drag and Drop Functionality to a Calendar

However, you can also drag and drop objects from outside the calendar. When you
want to enable this, use dataFlavor tags configured to allow the source object
(which will be something other than a calendarActivity object) to be dropped.
Before you begin:
It may be helpful to have an understanding of drag and drop functionality. For more
information, see Section 33.7, "Adding Drag and Drop Functionality to a Calendar."
You may also find it helpful to understand functionality that can be added using other
ADF Faces features. For more information, see Section 33.1.1, "Additional
Functionality for Drag and Drop."
To add drag and drop functionality to a calendar:
1. In the Component Palette, from the Operations panel, drag and drop a Calendar
Drop Target as a child to the calendar component.
2.

In the Insert Calendar Drop Target dialog, enter an expression for the
dropListener attribute that evaluates to a method on a managed bean that will
handle the event (you will create this code in Step 4).

3.

In the Property Inspector, set Actions. This value determines whether the activity
(or other source) can be moved, copied, or copied as a link, or any combination of
the three. If no action is specified, the default is COPY.

4.

In the managed bean inserted into the EL expression in Step 2, implement the
handler for the drop event.
This method must take a DropEvent event as a parameter and return a
DnDAction. The DnDAction is the action that will be performed when the source
is dropped. Valid return values are COPY, MOVE, and LINK, and are set when you
define the actions attribute in Step 3. This method should use the DropEvent to
get the transferable object, and from there, access the CalendarModel object
in the dragged data and from there, access the actual data. The listener can then
add that data to the model for the source and then return the DnDAction it
performed: DnDAction.COPY, DnDAction.MOVE or DnDAction.LINK;
otherwise, the listener should return DnDAction.NONE to indicate that the drop
was rejected.
The drop site for the drop event is an instance of the
oracle.adf.view.rich.dnd.CalendarDropSite class. For an example of a
drag and drop handler for a calendar, see the handleDrop method on the
oracle.adfdemo.view.calendar.rich.DemoCalendarBean managed
bean in the ADF Faces demo application.

5.

If the source for the activity is external to the calendar, drag a Data Flavor and
drop it as a child to the calendarDropTarget tag. This tag determines the type
of object that can be dropped onto the target, for example a String or a Date
object. Multiple dataFlavor tags are allowed under a single drop target to allow
the drop target to accept any of those types.

6.

In the Insert Data Flavor dialog, enter the class for the object that can be dropped
onto the target, for example java.lang.Object.
Tip: To specify a typed array in a dataFlavor tag, add brackets ([])
to the class name, for example, java.lang.Object[].

Adding Drag and Drop Functionality

33-21

Adding Drag and Drop Functionality for DVT Graphs

33.7.2 What You May Need to Know About Dragging and Dropping in a Calendar
For dragging and dropping activities within a calendar, users can drag and drop only
within a view. That is, users can drag an activity from one time slot to another in the
day view, but cannot cut an activity from a day view and paste it into a month view.
When the user is dragging and dropping activities in the day or week view, the
calendar marks the drop site by half-hour increments. The user cannot move any
all-day or multi-day activities in the day view.
In the week view, users can move all-day and multi-day activities, however, they can
be dropped only within other all-day slots. That is, the user cannot change an all-day
activity to an activity with start and end times. In the month view, users can move
all-day and multi-day activities to any other day.

33.8 Adding Drag and Drop Functionality for DVT Graphs
You can configure drag and drop for the DVT bubble and scatter graphs, which allows
the user to change the value of a marker by repositioning it. When you want users to
be able to drag and drop in a graph, you use the dragSource and dropTarget tags.
Additionally, you use the DataFlavor object to determine the valid Java type of the
sources for the drop target, in this case a GraphSelection object. You also must
implement any required functionality in response to the drag and drop action.
For example, you might have a scatterGraph component and you want the user to
be able to drag a human scatter marker to adjust the performance rating of an
employee, as shown in Figure 33–6.
Figure 33–5 Dragging and Dropping an Object

The scatterGraph component contains both a dragSource tag and a dropTarget
tag. You also use a dataFlavor tag to determine the type of object being dropped.
You also must implement a listener for the drop event. The object of the drop event is
called the transferable, which contains the payload of the drop. Your listener must
access the transferable object, and from there, use the DataFlavor object to
verify that the object can be dropped. You then use the drop event to get the target
component and update the property with the dropped object.

33.8.1 How to Add Drag and Drop Functionality for a DVT Graph
To add drag and drop functionality, first add source and target tags to the graph. Then
implement the event handler method that will handle the logic for the drag and drop

33-22 Web User Interface Developer's Guide for Oracle Application Development Framework

Adding Drag and Drop Functionality for DVT Graphs

action. For information about what happens at runtime, see Section 33.3.2, "What
Happens at Runtime."
Before you begin:
It may be helpful to have an understanding of drag and drop functionality. For more
information, see Section 33.8, "Adding Drag and Drop Functionality for DVT Graphs."
You may also find it helpful to understand functionality that can be added using other
ADF Faces features. For more information, see Section 33.1.1, "Additional
Functionality for Drag and Drop."
To add drag and drop functionality:
1. In the Component Palette, from the Operations panel, drag a Drop Target tag and
drop it as a child to the graph component.
2.

In the Insert Drop Target dialog, enter an expression that evaluates to a method on
a managed bean that will handle the event (you will create this code in Step 6).

3.

In the Insert Data Flavor dialog, enter
oracle.adf.view.faces.bi.component.graph.GraphSelection, which
is the class for the object that can be dropped onto the target. This entry will be
used to create a dataFlavor tag, which determines the type of object that can be
dropped onto the target.

4.

In the Property Inspector, set a value for Discriminant, if needed. A discriminant
is an arbitrary string used to determine which source can drop on the target. For
example, suppose you have two graphs that both accept an GraphSelection
object, GraphA and GraphB. You also have two sources, both of which are
GraphSelection objects. By setting a discriminant value on GraphA with a
value of alpha, only the GraphSelection source that provides the discriminant
value of alpha will be accepted.

5.

In the Structure window, select the dropTarget tag. In the Property inspector,
select MOVE as the value for Actions.

6.

In the Component Palette, from the Operations panel, drag and drop a Drag
Source as a child to the graph component.

7.

With the dragSource tag selected, in the Property Inspector set MOVE as the
allowed Action and add any needed discriminant, as configured for the
dataFlavor tag.

8.

In the managed bean referenced in the EL expression created in Step 2, create the
event handler method (using the same name as in the EL expression) that will
handle the drag and drop functionality.
This method must take a DropEvent event as a parameter and return a
DnDAction object, which is the action that will be performed when the source is
dropped, in this case DnDAction.MOVE. This method should check the
DropEvent event to determine whether or not it will accept the drop. If the
method accepts the drop, it should perform the drop and return the DnDAction
object it performed. Otherwise, it should return DnDAction.NONE to indicate that
the drop was rejected. The method must also check for the presence of the
dataFlavor object, in this case
oracle.adf.view.faces.bi.component.graph.GraphSelection.

Adding Drag and Drop Functionality

33-23

Adding Drag and Drop Functionality for DVT Gantt Charts

33.9 Adding Drag and Drop Functionality for DVT Gantt Charts
When you want users to be able to drag and drop between Gantt charts and other
components, you use the dragSource and dropTarget tags. Additionally, you use
the DataFlavor object to determine the valid Java types of sources for the drop
target. You also must implement any required functionality in response to the drag
and drop action. Both the projectGantt and schedulingGantt components
support drag and drop functionality.
For example, suppose you have an projectGantt component and you want the user
to be able to drag one timeline to a treeTable component and have that component
display information about the timeline, as shown in Figure 33–6.
Figure 33–6 Dragging and Dropping an Object

The projectGantt component contains a dragSource tag. And because the user
will drag the whole object and not just the String value of the output text that is
displayed, you use the dropTarget tag instead of the attributeDropTarget tag.
You also use a dataFlavor tag to determine the type of object being dropped. On this
tag, you can define a discriminant value. This is helpful if you have two targets and
two sources, all with the same object type. By creating a discriminant value, you can be
sure that each target will accept only valid sources. For example, suppose you have
two targets that both accept an TaskDragInfo object, TargetA and TargetB. Suppose
you also have two sources, both of which are TaskDragInfo objects. By setting a
discriminant value on TargetA with a value of alpha, only the TaskDragInfo source
that provides the discriminant value of alpha will be accepted.

33-24 Web User Interface Developer's Guide for Oracle Application Development Framework

Adding Drag and Drop Functionality for DVT Gantt Charts

You also must implement a listener for the drop event. The object of the drop event is
called the transferable, which contains the payload of the drop. Your listener must
access the transferable object, and from there, use the DataFlavor object to
verify that the object can be dropped. You then use the drop event to get the target
component and update the property with the dropped object.

33.9.1 How to Add Drag and Drop Functionality for a DVT Component
To add drag and drop functionality, first add tags to a component that define it as a
target for a drag and drop action. Then implement the event handler method that will
handle the logic for the drag and drop action. Last, you define the sources for the drag
and drop. For information about what happens at runtime, see Section 33.3.2, "What
Happens at Runtime." For information about using the clientDropListener
attribute, see Section 33.3.3, "What You May Need to Know About Using the
ClientDropListener."
Before you begin:
It may be helpful to have an understanding of drag and drop functionality. For more
information, see Section 33.9, "Adding Drag and Drop Functionality for DVT Gantt
Charts."
You may also find it helpful to understand functionality that can be added using other
ADF Faces features. For more information, see Section 33.1.1, "Additional
Functionality for Drag and Drop."
To add drag and drop functionality:
1. In the Component Palette, from the Operations panel, drag a Drop Target tag and
drop it as a child to the target component.
2.

In the Insert Drop Target dialog, enter an expression that evaluates to a method on
a managed bean that will handle the event (you will create this code in Step 6).
Tip: You can also intercept the drop on the client by populating the
clientDropListener attribute. For more information, see
Section 33.3.3, "What You May Need to Know About Using the
ClientDropListener".

3.

In the Insert Data Flavor dialog, enter the class for the object that can be dropped
onto the target, for example java.lang.Object. This selection will be used to
create a dataFlavor tag, which determines the type of object that can be dropped
onto the target. Multiple dataFlavor tags are allowed under a single drop target
to allow the drop target to accept any of those types.
Tip: To specify a typed array in a DataFlavor tag, add brackets ([])
to the class name, for example, java.lang.Object[].

4.

In the Property Inspector, set a value for Discriminant, if needed. A discriminant
is an arbitrary string used to determine what sources of the type specified by the
dataFlavor will be allowed as a source.

5.

In the Structure window, select the dropTarget tag. In the Property inspector,
select a value for Actions. This defines what actions are supported by the drop
target. Valid values can be COPY (copy and paste), MOVE (cut and paste), and LINK
(copy and paste as a link), for example:.
MOVE COPY

Adding Drag and Drop Functionality

33-25

Adding Drag and Drop Functionality for DVT Gantt Charts

If no actions are specified, the default is COPY.
Example 33–10 shows the code for a dropTarget component that takes a
TaskDragInfo object as a drop source. Note that because COPY was set as the
value for the actions attribute, that will be the only allowed action.
Example 33–10 JSP Code for a dropTarget tag



















6.

In the managed bean referenced in the EL expression created in Step 2, create the
event handler method (using the same name as in the EL expression) that will
handle the drag and drop functionality.
This method must take a DropEvent event as a parameter and return a
DnDAction object, which is the action that will be performed when the source is
dropped. Valid return values are DnDAction.COPY, DnDAction.MOVE, and
DnDAction.LINK, and were set when you defined the target attribute in Step 5.
This method should check the DropEvent event to determine whether or not it
will accept the drop. If the method accepts the drop, it should perform the drop
and return the DnDAction object it performed. Otherwise, it should return
DnDAction.NONE to indicate that the drop was rejected.
The method must also check for the presence for each dataFlavor object in
preference order.
Tip: If your target has more than one defined dataFlavor object,
then you can use the
Transferable.getSuitableTransferData() method, which
returns a List of TransferData objects available in the
Transferable object in order, from highest suitability to lowest.

The DataFlavor object defines the type of data being dropped, for example
java.lang.Object, and must be as defined in the DataFlavor tag on the JSP,
as created in Step 3.

33-26 Web User Interface Developer's Guide for Oracle Application Development Framework

Adding Drag and Drop Functionality for DVT Gantt Charts

Tip: To specify a typed array in a DataFlavor object, add brackets
([]) to the class name, for example, java.lang.Object[].

DataFlavor objects support polymorphism so that if the drop target
accepts java.util.List, and the transferable object contains a
java.util.ArrayList, the drop will succeed. Likewise, this
functionality supports automatic conversion between Arrays and
Lists.
If the drag and drop framework doesn't know how to represent a
server DataFlavor object on the client component, the drop target
will be configured to allow all drops to succeed on the client.
Example 33–11 shows a handler method that copies a TaskDragInfo object from
the event payload and assigns it to the component that initiated the event.
Example 33–11 Event Handler Code for a dropListener
public DnDAction onTableDrop(DropEvent evt)
{
// retrieve the information about the task dragged
DataFlavor _flv = DataFlavor.getDataFlavor(TaskDragInfo.class, null);
Transferable _transferable = evt.getTransferable();
// if there is no data in the transferable, then the drop is unsuccessful
TaskDragInfo _info = _transferable.getData(_flv);
if (_info == null)
return DnDAction.NONE;
// find the task
Task _draggedTask = findTask(_info.getTaskId());
if (_draggedTask != null) {
// process the dragged task here and indicate the drop is successful by returning DnDAction.COPY
return DnDAction.COPY;
}
else
return DnDAction.NONE;
}
7.

In the Component Palette, from the Operations panel, drag and drop a Drag
Source as a child to the source component.

8.

With the dragSource tag selected, in the Property Inspector set the allowed
Actions and any needed discriminant, as configured for the target.

Adding Drag and Drop Functionality

33-27

Adding Drag and Drop Functionality for DVT Gantt Charts

33-28 Web User Interface Developer's Guide for Oracle Application Development Framework

34
Using Different Output Modes

34

This chapter describes how you can have your pages display in modes suitable for
printing and emailing.
This chapter includes the following sections:
■

Section 34.1, "About Using Different Output Modes"

■

Section 34.2, "Displaying a Page for Print"

■

Section 34.3, "Creating Emailable Pages"

34.1 About Using Different Output Modes
ADF Faces allows you to output your page in a simplified mode either for printing or
for emailing. For example, you may want users to be able to print a page (or a portion
of a page), but instead of printing the page exactly as it is rendered in a web browser,
you want to remove items that are not needed on a printed page, such as scroll bars
and buttons. If a page is to be emailed, the page must be simplified so that email
clients can correctly display it.
By default, when the ADF Faces framework detects that an
application is being crawled by a search engine, it outputs pages in a
simplified format for the crawler, similar to that for an emailable page.
If you want to generate special content for web crawlers, you can use
the EL-reachable Agent interface to detect when an agent is crawling
the site, and then direct the agent to a specified link, for example:

Note:





For more information, see the Trinidad JavaDoc.
For displaying printable pages, ADF Faces offers the
showPrintablePageBehavior tag that, when used in conjunction with a command
component, allows users to view a simplified version of the page in their browser,
which they can then print.
For email support, ADF Faces provides an API that can be used to convert a page to
one that is suitable for display in either Microsoft Outlook 2007 or Mozilla
Thunderbird 2.0.

Using Different Output Modes 34-1

About Using Different Output Modes

Tip: The current output mode (email or printable) can be
reached from AdfFacesContext. Because this context is EL
reachable, you can use EL to bind to the output mode from the JSP
page. For example, you might allow a graphic to be rendered only if
the current mode is not email using the following expression:


You can determine the current mode using
AdfFacesContext.getOutputMode().

34.1.1 Output Mode Use Cases
Most web pages are not suitable for print or for emailing, but users may need that
functionality. For example, in the File Explorer application, you could place a
commandButton component inside the toolbar of the panelCollection component
that contains the table, as shown in Figure 34–1.
Figure 34–1 Button to Print Part of a Page

When the user clicks the button, the page is displayed in a new browser window (or
tab, depending on the browser) in a simplified form, as shown in Figure 34–2.
Figure 34–2 Printable Version of the Page

Only the contents of the table are displayed for printing. All extraneous components,
such as the tabs, the toolbar, and the scroll bars, are not rendered.
There may be occasions when you need a page in your application to be emailed. For
example, purchase orders created on the web are often emailed to the purchaser at the
end of the session. However, because email clients do not support external stylesheets
which are used to render to web browsers, you can’t email the same page, as it would
not be rendered correctly.
Say you have a page that displays a purchase order, as shown in Figure 34–3.

34-2 Web User Interface Developer's Guide for Oracle Application Development Framework

About Using Different Output Modes

Figure 34–3 Purchase Order Web Page

When the user clicks the Emailable Page link at the top, an actionListener method
or another service appends
org.apache.myfaces.trinidad.agent.email=true to the current URL and
emails the page. Figure 34–4 shows the page as it appears in an email client.

Using Different Output Modes 34-3

Displaying a Page for Print

Figure 34–4 Page in an Email Client

34.2 Displaying a Page for Print
You place the showPrintablePageBehavior tag as a child to a command
component. When clicked, the framework walks up the component tree, starting with
the component that is the parent to the printableBehavior tag, until it reaches a
panelSplitter or a panelAccordion or the root of the tree (whichever comes
first). The tree is rendered from there. Additionally, certain components that are not
needed in print version (such as buttons, tabs, and scrollbars) are omitted.
When the command component is clicked, the action event is canceled. Instead, a
request is made to the server for the printable version of the page.

34.2.1 How to Use the showPrintablePageBehavior Tag
The showPrintablePageBehavior tag is used as a direct child of a command
component.
To use the showPrintablePageBehavior tag:
1. In one of the layout components, add a command component in the facet that
contains the content you would like to print. For procedures, see Section 20.3.1,
"How to Use Command Buttons and Command Links."

34-4 Web User Interface Developer's Guide for Oracle Application Development Framework

Creating Emailable Pages

Note: While you can insert a showPrintablePageBehavior
component outside of a layout component to allow the user to print
the entire page, the printed result will be roughly in line with the
layout, which may mean that not all content will be visible. Therefore,
if you want the user to be able to print the entire content of a facet, it is
important to place the command component and the
showPrintablePageBehavior component within the facet whose
contents users would typically want to print. If more than one facet
requires printing support, then insert one command component and
showPrintablePageBehavior tag into each facet. To print all
contents, the user then has to execute the print command one facet at a
time.
2.

In the Component Palette, from the Operations panel, drag a Show Printable Page
Behavior and drop it as a child to the command component.

34.3 Creating Emailable Pages
The ADF Faces framework provides you with automatic conversion of a JSF page so
that it will render correctly in the Microsoft Outlook 2007 and Mozilla Thunderbird 2.0
email clients.
Not all components can be rendered in an email client. The following components can
be converted so that they can render properly in an email client:
■

document

■

panelHeader

■

panelFormLayout

■

panelGroupLayout

■

panelList

■

spacer

■

showDetailHeader

■

inputText (renders as readOnly)

■

inputComboBoxListOfValues (renders as readOnly)

■

inputNumberSlider (renders as readOnly)

■

inputNumberSpinbox (renders as readOnly)

■

inputRangeSlider (renders as readOnly)

■

outputText

■

selectOneChoice (renders as readOnly)

■

panelLabelAndMessage

■

image

■

table

■

column

■

goLink (renders as text)

■

commandImageLink (renders as text)
Using Different Output Modes 34-5

Creating Emailable Pages

■

commandLink (renders as text)

■

goImageLink (renders as text)

34.3.1 How to Create an Emailable Page
You notify the ADF Faces framework to convert your page to be rendered in an email
client by appending a request parameter to the URL for the page to be emailed.
Before you begin:
It may be helpful to have an understanding of how components will display in an
emailable page. For more information, see Section 34.3, "Creating Emailable Pages."
To create an emailable page:
1. Insert a command component onto the page to be emailed. For more information,
see Chapter 20, "Working with Navigation Components."
2.

In a managed bean, create an actionListener method or another service that
appends org.apache.myfaces.trinidad.agent.email=true to the
current URL and emails the page.

3.

Select the command component, and in the Property Inspector, set the method or
service as the value for ActionListener.

34.3.2 How to Test the Rendering of a Page in an Email Client
Before you complete the development of a page, you may want to test how the page
will render in an email client. You can easily do this using a goButton component.
To test an emailable page:
1. In the Component Palette, from the General Controls panel, drag and drop a
Button (Go) anywhere onto the page.
2.

In the Property Inspector, expand the Common section and set the Destination to
be the page’s name plus
org.apache.myfaces.trinidad.agent.email=true.
For example, if your page’s name is myPage, the value of the destination attribute
should be:
myPage.jspx?org.apache.myfaces.trinidad.agent.email=true

3.

Right-click the page and choose Run to run the page in the default browser.
The Configure Default Domain dialog displays the first time your run your
application and start a new domain in Integrated WebLogic Server. Use the dialog
to define an administrator password for the new domain. Passwords you enter can
be eight characters or more and must have a numeric character.

4.

Once the page displays in the browser, click the goButton you added to the page.
This will again display the page in the browser, but converted to a page that can be
handled by an email client.

5.

In your browser, view the source of the page. For example, in Mozilla Firefox, you
would select View > Page Source. Select the entire source and copy it.

6.

Create a new message in your email client. Paste the page source into the message
and send it to yourself.

34-6 Web User Interface Developer's Guide for Oracle Application Development Framework

Creating Emailable Pages

Tip: Because you are pasting HTML code, you will probably need to
use an insert command to insert the HTML into the email body. For
example, in Thunderbird, you would choose Insert > HTML.
7.

If needed, create a skin specifically for the email version of the page using an
agent. Example 34–1 shows how you might specify the border on a table rendered
in email.

Example 34–1

Skin for Emailable Page

af|table {
border: 1px solid #636661;
}
@agent email {
af|table
{border:none}
}
af|table::column-resize-indicator {
border-right: 2px dashed #979991;
}

For more information about creating skins, see Chapter 28, "Customizing the
Appearance Using Styles and Skins."

34.3.3 What Happens at Runtime: How ADF Faces Converts JSF Pages to Emailable
Pages
When the ADF Faces framework receives the request parameter
org.apache.myfaces.trinidad.agent.email=true in the Render Response phase, the
associated phase listener sets an internal flag that notifies the framework to do the
following:
■

Remove any JavaScript from the HTML.

■

Add all CSS to the page, but only for components included on the page.

■

Remove the CSS link from the HTML.

■

Convert all relative links to absolute links.

■

Render images with absolute URLs.

Using Different Output Modes 34-7

Creating Emailable Pages

34-8 Web User Interface Developer's Guide for Oracle Application Development Framework

35
Using the Active Data Service with an
Asynchronous Backend

35

This chapter provides information on registering an asynchronous backend to provide
real-time data updates to ADF Faces components.
This chapter includes the following sections:
■

Section 35.1, "About the Active Data Service"

■

Section 35.2, "Process Overview for Using Active Data Service"

■

Section 35.3, "Implement the ActiveModel Interface in a Managed Bean"

■

Section 35.4, "Pass the Event Into the Active Data Service"

■

Section 35.5, "Register the Data Update Event Listener"

■

Section 35.6, "Configure the ADF Component to Display Active Data"

35.1 About the Active Data Service
The Fusion technology stack includes the Active Data Service (ADS), which is a
server-side push framework that allows you to provide real-time data updates for
ADF Faces components. You bind ADF Faces components to a data source and ADS
pushes the data updates to the browser client without requiring the browser client to
explicitly request it. For example, you may have a table bound to attributes of an ADF
data control whose values change on the server periodically, and you want the
updated values to display in the table. You can create a Java bean to implement the
ActiveModel interface and register it as an event listener to notify the component of
a data event from the backend, and the component rerenders the changed data with
the new value highlighted, as shown in Figure 35–1.
Figure 35–1 Table Displays Updated Data as Highlighted

Using the Active Data Service with an Asynchronous Backend

35-1

Process Overview for Using Active Data Service

35.1.1 Active Data Service Use Cases and Examples
Using ADS is an alternative to using automatic partial page rendering (PPR) to
rerender data that changes on the backend as a result of business logic associated with
the ADF data control bound to the ADF Faces component. Whereas automatic PPR
requires sending a request to the server (typically initiated by the user), ADS enables
changed data to be pushed from the data store as the data arrives on the server. Also,
in contrast to PPR, ADS makes it possible for the component to rerender only the
changed data instead of the entire component. This makes ADS ideal for situations
where the application needs to react to data that changes periodically.
To use this functionality, you must configure the application to use ADS. If your
application services do not support ADS, then you also need to create a proxy of the
service so that the components can display the data as it updates in the source.
Any ADF Faces page can use ADS. However, you can configure only the following
ADF Faces components to work with active data:
■

activeCommandToolbarButton

■

activeImage

■

activeOutputText

■

table
Do not use filtering on a table that will be using active data.
Once a table is filtered at runtime, active data cannot be displayed.
Currently, ADS supports table components with the outputText
component contained within a column; other components are not
supported inside the table column.

Note:

■

tree

■

treeTable

■

DVT graph, gauge, and geographical map components

For details about the active data service framework and important configuration
information, see Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application
Development Framework.

35.2 Process Overview for Using Active Data Service
To use ADS, you can optionally configure your application to determine the method of
data transport, as well as other performance options.
Before you begin:
Complete the following tasks:
■

■

Implement the logic to fire the active data events asynchronously from the data
source. For example, this logic might be a business process that updates the
database, or a JMS client that gets notified from JMS.
The Active Data framework does not support complicated business logic or
transformations that require the ADF runtime context, such as a user profile or
security. For example, the framework cannot convert an ADF context
locale-dependent value and return a locale-specific value. Instead, you need to
have your data source handle this before publishing the data change event.

35-2 Web User Interface Developer's Guide for Oracle Application Development Framework

Implement the ActiveModel Interface in a Managed Bean

■

Before users can run the ADF Faces page with ADS configured for the application,
they must disable the popup blocker for their web browser. Active data is not
supported in web browsers that have popup blockers enabled.

To use the Active Data Service:
1.

Optionally, configure ADS to determine the data transport mode, as well as to set
other configurations, such as a latency threshold and reconnect information.
Configuration for ADS is done in the adf-config.xml file.
For details about configuring ADS, see Oracle Fusion Middleware Fusion Developer's
Guide for Oracle Application Development Framework.

2.

Create a backing bean that implements the ActiveModel interface and register it
as the listener for active data events from your backend.

3.

Create a class that extends the BaseActiveDataModel API to pass the Event
object to the ADS framework.

4.

Register a data change listener for data change events from the backend.

5.

In the web page, configure the ADF Faces component to capture and display the
pushed data by adding an expression to name the managed bean that implements
the the ADF component that you use to capture and display the pushed data.

35.3 Implement the ActiveModel Interface in a Managed Bean
Create a backing bean that contains the active model implementation as its property.
This class uses an ADS decorator class to wrap the JSF model. This class should also
implement a callback from the backend that will push data into the ADS framework.
You need to create a Java class that subclasses one of the following ADS decorator
classes:
■

ActiveCollectionModelDecorator class

■

ActiveDataModelDecorator class (for use with graphs)

■

ActiveGeoMapDataModelDecorator class

■

ActiveGaugeDataModelDecorator class

These classes are wrapper classes that delegate the active data functionality to a
default implementation of ActiveDataModel. The ActiveDataModel class listens
for data change events and interacts with the Event Manager.
Specifically, when you implement the ActiveModel interface, you accomplish the
following:
■

■

Wraps the JSF model interface. For example, the
ActiveCollectionModelDecorator class wraps the CollectionModel
class.
Generates active data events based on data change events from the data source.

To implement the ActiveModel interface, you need to implement methods on your
Java class that gets the model to which the data is being sent and registers itself as the
listener of the active data source (as illustrated in Example 35–1):
1.

Create a Java class that extends the decorator class appropriate for your
component.

Using the Active Data Service with an Asynchronous Backend

35-3

Implement the ActiveModel Interface in a Managed Bean

Example 35–1 shows a StockManager class that extends
ActiveCollectionModelDecorator. In this case, the data is displayed for an
ADF Faces table component.
2.

Implement the methods of the decorator class that will return the
ActiveDataModel class and implement the method that returns the scalar
model.
Example 35–1 shows an implementation of the getCollectionModel() method
that registers with an existing asynchronous backend. The method returns the list
of stocks collection from the backend.

3.

Implement a method that creates application-specific events that can be used to
insert or update data on the active model.
Example 35–1 shows the onStockUpdate() callback method from the backend,
which uses the active model (an instance of ActiveStockModel) to create
ActiveDataUpdateEvent objects to push data to the ADF Faces component.

Example 35–1

Extend the Decorator Class

package sample.oracle.ads;
import
import
import
import

java.util.List;
sample.backend.IBackendListener;
sample.bean.StockBean;
sample.oracle.model.ActiveStockModel;

import
import
import
import

oracle.adf.view.rich.event.ActiveDataEntry;
oracle.adf.view.rich.event.ActiveDataUpdateEvent;
oracle.adf.view.rich.model.ActiveCollectionModelDecorator;
oracle.adf.view.rich.model.ActiveDataModel;

import oracle.adfinternal.view.faces.activedata.ActiveDataEventUtil;
import org.apache.myfaces.trinidad.model.CollectionModel;
import org.apache.myfaces.trinidad.model.SortableModel;
// 1. This example wraps the existing collection model in the page and implements
//
the ActiveDataModel interface to enable ADS for the page.
public StockManager extends ActiveCollectionModelDecorator implements
IBackendListener
{
// 2. Implement methods from ADF ActiveCollectionModelDecorator class to
//
return the model.
@Override
public ActiveDataModel getActiveDataModel()
{
return stockModel;
}
@Override
protected CollectionModel getCollectionModel()
{
if(collectionModel == null)
{
// connect to a backend system to get a Collection
List stocks = FacesUtil.loadBackEnd().getStocks();
// make the collection become a (Trinidad) CollectionModel
collectionModel = new SortableModel(stocks);

35-4 Web User Interface Developer's Guide for Oracle Application Development Framework

Implement the ActiveModel Interface in a Managed Bean

}
return collectionModel;
}
// 3. Implement a callback method to create active data events and deliver to
//
the ADS framework.
/**
* Callback from the backend to push new data to our decorator.
* The decorator itself notifies the ADS system that there was a data change.
*
* @param key the rowKey of the updated Stock
* @param updatedStock the updated stock object
*/
@Override
public void onStockUpdate(Integer rowKey, StockBean stock)
{
ActiveStockModel asm = getActiveStockModel();
// start the preparation for the ADS update
asm.prepareDataChange();
// Create an ADS event, using an _internal_ util.
// This class is not part of the API
ActiveDataUpdateEvent event = ActiveDataEventUtil.buildActiveDataUpdateEvent(
ActiveDataEntry.ChangeType.UPDATE, // type
asm.getCurrentChangeCount(), // changeCount
new Object[] {rowKey}, // rowKey
null, //insertKey, null as we don't insert stuff
new String[] {"value"}, // attribute/property name that changes
new Object[] { stock.getValue()} // the payload for the above attribute
);
// Deliver the new Event object to the ADS framework
asm.notifyDataChange(event);
}
/**
* Typesafe caller for getActiveDataModel()
* @return
*/
protected ActiveStockModel getActiveStockModel()
{
return (ActiveStockModel) getActiveDataModel();
}
// properties
private CollectionModel collectionModel; // see getCollectionModel()...
private ActiveStockModel stockModel = new ActiveStockModel();
}

Register the class as a managed bean in the faces-config.xml file. Example 35–2
shows the bean StockManager is registered. Defining the managed bean allows you
to specify the managed bean in an expression for the ADF Faces component’s value
property.

Using the Active Data Service with an Asynchronous Backend

35-5

Pass the Event Into the Active Data Service

Example 35–2

Register as a Managed Bean

...

stockManager

oracle.afdemo.view.feature.rich.StockManager

session


35.3.1 What You May Need to Know About Read Consistency
Using active data means that your component has two sources of data: the active data
feed and the standard data fetch. Because of this, you must make sure your application
maintains read consistency.
For example, say your page contains a table and that table has active data enabled. The
table has two methods of delivery from which it updates its data: normal table data
fetch and active data push. Say the back end data changes from foo to bar to fred.
For each of these changes, an active data event is fired. If the table is refreshed before
those events hit the browser, the table will display fred because standard data fetch
will always get the latest data. But then, because the active data event might take
longer, some time after the refresh the data change event would cause foo to arrive at
the browser, and so the table would update to display foo instead of fred for a
period of time. Therefore, you must implement a way to maintain the read
consistency.
To achieve read consistency, the ActiveDataModel has the concept of a change count,
which effectively timestamps the data. Both data fetch and active data push need to
maintain this changeCount object by monotonically increasing the count, so that if
any data returned has a lower changeCount, the active data event can throw it away.
Example 35–3 shows how you can use your implementation of the
ActiveDataModel class to maintain read consistency.

35.4 Pass the Event Into the Active Data Service
You need to create a class that extends BaseActiveDataModel class to pass the
event created by your managed bean. The ActiveDataModel class listens for data
change events and interacts with the Event Manager. Specifically, the methods you
implement do the following:
■

■

Optionally, starts and stops the active data and the ActiveDataModel object,
and registers and unregisters listeners to the data source.
Manages listeners from the Event Manager and pushes active data events to the
Event Manager.

Example 35–3 shows the notifyDataChange() method of the model passes the
Event object to the ADS framework, by placing the object into the
fireActiveDataUpdate() method.
Example 35–3

Pass the Event Object into ADS

import java.util.Collection;
import java.util.concurrent.atomic.AtomicInteger;
import oracle.adf.view.rich.activedata.BaseActiveDataModel;

35-6 Web User Interface Developer's Guide for Oracle Application Development Framework

Register the Data Update Event Listener

import oracle.adf.view.rich.event.ActiveDataUpdateEvent;
public class ActiveStockModel extends BaseActiveDataModel
{
// -------------- API from BaseActiveDataModel ---------@Override
protected void startActiveData(Collection