ADFDI
ADFDI
ADFDI
June 2013 Documentation for Oracle ADF Desktop Integration developers that describes how to extend the functionality provided by a Fusion web application to desktop applications.
Oracle Fusion Middleware Developing Applications with Oracle ADF Desktop Integration 12c (12.1.2) E23244-01 Copyright 2013, Oracle and/or its affiliates. All rights reserved. Primary Author: Himanshu Marathe 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 END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government. 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 ............................................................................................................................................................... xiii
Audience..................................................................................................................................................... Documentation Accessibility ................................................................................................................... Related Documents ................................................................................................................................... Conventions ............................................................................................................................................... xiii xiii xiii xiii
Installing ADF Desktop Integration ................................................................................. 3-4 How to Set Up ADF Desktop Integration .................................................................. 3-4 Removing ADF Desktop Integration ................................................................................ 3-6 Upgrading ADF Desktop Integration ............................................................................... 3-6 How to Migrate an Integrated Excel Workbook to the Current Version of ADF Desktop Integration ................................................................................................................. 3-7 Using an Integrated Excel Workbook with Older Versions of ADF Desktop Integration 3-8 Using ADF Desktop Integration on a System with Multiple Instances of JDeveloper .... 3-8
iv
5.13 Using the Cell Context Menu ......................................................................................... 5-16 5.14 Removing ADF Desktop Integration Components ......................................................... 5-17 5.15 Exporting and Importing Excel Workbook Integration Metadata .................................. 5-19 5.15.1 How to Export Workbook Integration Metadata ..................................................... 5-19 5.15.2 How to Import Workbook Integration Metadata ..................................................... 5-20 5.15.3 What You May Need to Know About Exporting and Importing Excel Workbook Integration Metadata ............................................................................................... 5-21
7.7.1 7.8 7.8.1 7.8.2 7.8.3 7.8.4 7.8.5 7.8.6 7.9 7.9.1 7.9.2 7.9.3 7.10 7.10.1 7.10.2 7.11 7.11.1 7.11.2 7.11.3 7.12 7.13 7.13.1 7.13.2 7.14 7.14.1 7.14.2 7.15 7.16 7.16.1 7.16.2 7.16.3 7.16.4 7.17 7.17.1 7.17.2 7.18 7.18.1 7.18.2 7.19
vi
How to Configure an ADF Table Component to Insert Data Using a View Object's Operations ............................................................................................................... 7-13 Configuring an ADF Component to Upload Changes from an ADF Table Component 7-15 How to Configure an ADF Component to Upload Data from an ADF Table Component .............................................................................................................. 7-15 What Happens at Runtime: How the ADF Table Component Uploads Data .......... 7-17 What Happens at Runtime: How the ReadOnly EL Expression Is Evaluated During Upload ..................................................................................................................... 7-18 What Happens at Runtime: Upload Failure ............................................................ 7-18 How to Create a Custom Upload Dialog ................................................................. 7-19 What Happens at Runtime: Custom Upload Dialog ................................................ 7-19 Configuring an ADF Table Component to Upload Changes Using UploadAllOrNothing Action ............................................................................................................................. 7-20 How to Configure an ADF Component to use UploadAllOrNothing Action .......... 7-20 What Happens at Runtime: UploadAllOrNothing Action is Invoked ..................... 7-21 Limiting the Amount of Changed Data That Can Be Uploaded With UploadAllOrNothing Action ................................................................................... 7-21 Configuring an ADF Table Component to Delete Rows in the Fusion Web Application ...... 7-21 How to Configure an ADF Table Component to Delete Rows in the Fusion Web Application .............................................................................................................. 7-22 What Happens at Runtime: How the ADF Table Component Deletes Rows in a Fusion Web Application ...................................................................................................... 7-23 Batch Processing in an ADF Table Component .............................................................. 7-24 How to Configure Batch Options for an ADF Table Component ........................... 7-24 Row Flagging in an ADF Table Component ............................................................ 7-25 Troubleshooting Errors While Uploading Data ....................................................... 7-26 Special Columns in the ADF Table Component ............................................................ 7-26 Configuring ADF Table Component Key Column ......................................................... 7-28 How to Configure the Key Column ......................................................................... 7-28 How to Manually Add the Key Column At Design Time ........................................ 7-29 Creating a List of Values in an ADF Table Component Column .................................... 7-30 How to Create a List of Values in an ADF Table Component Column .................... 7-30 What Happens at Runtime: How the ADF Table Column Renders a List of Values 7-32 Adding a ModelDrivenColumnComponent Subcomponent to Your ADF Table Component ..................................................................................................................... 7-32 Adding a Dynamic Column to Your ADF Table Component ........................................ 7-33 How to Configure a Dynamic Column .................................................................... 7-34 What Happens at Runtime: How Data Is Downloaded or Uploaded In a Dynamic Column .................................................................................................................... 7-34 How to Specify Header Labels for Dynamic Columns ............................................ 7-35 How to Specify Styles for Dynamic Columns According to Attribute Data Type ... 7-36 Creating an ADF Read-Only Table Component ............................................................. 7-36 How to Insert an ADF Read-only Table Component ............................................... 7-37 How to Manually Add a Column to the ADF Read-only Table Component ........... 7-38 Limiting the Number of Rows Your Table-Type Component Downloads .................... 7-39 How to Limit the Number of Rows a Component Downloads ............................... 7-39 What Happens at Runtime: How the RowLimit Property Works ........................... 7-40 Clearing the Values of Cached Attributes in an ADF Table Component ....................... 7-41
7.19.1 7.19.2 7.20 7.21 7.21.1 7.21.2 7.21.3 7.22 7.22.1 7.22.2
How to Clear the Values of Cached Attributes in an ADF Table Component ......... 7-41 What Happens at Runtime: How the ADF Table Component Clears Cached Values .... 7-41 Tracking Changes in an ADF Table Component ............................................................ 7-42 Evaluating EL Expression for ReadOnly Properties ....................................................... 7-42 What Happens at Runtime: Evaluating EL Expression While Downloading Data .. 7-42 What Happens at Runtime: Evaluating EL Expression While Uploading Data or Tracking Changes .................................................................................................... 7-43 What You May Need to Know About Evaluating EL Expression While Uploading Data or Tracking Changes ................................................................................................ 7-43 Using Explicit Worksheet Setup Action ......................................................................... 7-43 How to Configure Explicit Worksheet Setup Action ............................................... 7-44 What You May Need to Know About Explicit Worksheet Setup Action ................. 7-45
vii
Creating ADF Databound Search Forms in an Integrated Excel Workbook .................. 8-28 How to Create a Search Form in an Integrated Excel Workbook ............................. 8-29 How to Create a Search Form using a Web Page in an Integrated Excel Workbook 8-31 Creating a Form in an Integrated Excel Workbook ........................................................ 8-33 Creating Dependent Lists of Values in an Integrated Excel Workbook ......................... 8-34 How to Create a Dependent List of Values in an Excel Worksheet ......................... 8-37 What Happens at Runtime: How the Excel Worksheet Renders a Dependent List of Values ...................................................................................................................... 8-38 8.8.3 How to Create a Dependent List of Values in an ADF Table Component's Columns .... 8-39 8.8.4 What Happens at Runtime: How the ADF Table Component Column Renders a Dependent List of Values ......................................................................................... 8-40 8.8.5 Creating a Dependent List of Values in an Excel Worksheet and an ADF Table Component Column ................................................................................................ 8-41 8.8.6 What Happens at Runtime: How the Excel Worksheet and the ADF Table Component Column Render a Dependent List of Values ........................................................... 8-43 8.9 Using EL Expression to Generate an Excel Formula ...................................................... 8-44 8.9.1 How to Configure a Cell to Display a Hyperlink Using EL Expression .................. 8-45 8.9.2 What Happens at Runtime: How a Cell Displays a Hyperlink using an EL Expression . 8-45 8.10 Using Calculated Cells in an Integrated Excel Workbook .............................................. 8-46 8.10.1 How to Calculate the Sum of a Table-Type Component Column ............................ 8-47 8.10.2 What Happens at Runtime: How Excel Calculates the Sum of a Table-Type Component Column ................................................................................................ 8-47 8.11 Using Macros in an Integrated Excel Workbook ........................................................... 8-48
viii
Branding Your Integrated Excel Workbook ................................................................... 9-12 How to Brand an Integrated Excel Workbook ......................................................... 9-12 What Happens at Runtime: the BrandingItems Group of Properties ....................... 9-13 Using Worksheet Protection ........................................................................................... 9-14 How to Enable Worksheet Protection ...................................................................... 9-14 What Happens at Runtime: How the Locked Property Works ................................ 9-15 What You May Need to Know About Worksheet Protection .................................. 9-16
11
ix
Providing Client-Side Validation for an Integrated Excel Workbook ............................ 12-2 Error Reporting in an Integrated Excel Workbook ......................................................... 12-3 Error Reporting Using EL Expressions .................................................................... 12-3 Error Reporting Using Component Actions ............................................................ 12-4 Providing a Row-by-Row Status on an ADF Table Component .................................... 12-6 Adding Detail to Error Messages in an Integrated Excel Workbook .............................. 12-7 Handling Data Conflicts When Uploading Data from a Workbook ............................... 12-7 How to Configure a Workbook to Handle Data Conflicts When Uploading Data .. 12-8 What Happens at Runtime: How Data Conflicts Are Handled ............................... 12-8
13
15 Using an Integrated Excel Workbook Across Multiple Web Sessions and in Disconnected Mode
15.1
x
15.1.1 Disconnected Workbooks Use Cases and Examples ................................................ 15-2 15.1.2 Additional Functionality for Disconnected Workbooks .......................................... 15-2 15.2 Restore Server Data Context Between Sessions .............................................................. 15-2 15.2.1 How to Configure an Integrated Excel Workbook to Restore Server Data Context . 15-3 15.2.2 What Happens at Runtime: How the Integrated Excel Workbook Restores Server Data Context ..................................................................................................................... 15-4 15.3 Caching of Static Information in an Integrated Excel Workbook ................................... 15-4 15.4 Caching Lists of Values for Use in Disconnected Mode ................................................. 15-5
xi
E String Keys in the Overridable Resources F Java Data Types Supported By ADF Desktop Integration G Using the ADF Desktop Integration Model API
G.1 G.2 G.2.1 About the Temporary Row Object .................................................................................. G-1 About ADF Desktop Integration Model API ................................................................... G-2 How to Add ADF Desktop Integration Model API Library to Your JDeveloper Project G-2 G.3 ADF Desktop Integration Model API Classes and Methods ........................................... G-3 G.3.1 The oracle.adf.desktopintegration.model.ModelHelper Class .................................. G-3 G.3.1.1 The getAdfdiTempChildRow Method ............................................................... G-3 G.3.1.2 The getAdfdiTempRowForView Method .......................................................... G-4 G.3.1.3 The getChildViewDef Method ........................................................................... G-4
xii
Preface
Welcome to the Developing Applications with Oracle ADF Desktop Integration.
Audience
This manual is intended for enterprise developers who configure desktop applications to integrate with the Oracle Application Development Framework (Oracle ADF).
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:
Developing Fusion Web Applications with Oracle Application Development Framework Developing Web User Interfaces with Oracle ADF Faces
Conventions
The following text conventions are used in this document:
Convention boldface Meaning Boldface type indicates graphical user interface elements (for example, menus and menu items, buttons, tabs, dialog controls), including options that you select. Italic type indicates book titles, emphasis, or placeholder variables for which you supply particular values.
italic
xiii
Convention monospace
Meaning Monospace type indicates language and syntax elements, directory and file names, URLs, text that appears on the screen, or text that you enter.
xiv
All procedures and graphics have been updated to use Windows 7 as the primary Windows Operating System. All demo examples and graphics have been updated to use Summit Sample Application for ADF Desktop Integration. Some Administrator-related content has been moved to Administering Oracle ADF Applications. System requirements and installation instructions have been updated. See Section 3.4, "Installing ADF Desktop Integration." Add integrated Excel workbook to a project in JDeveloper. See Section 4.2, "Adding an Integrated Excel Workbook to a Fusion Web Application." Create and configure ADF Desktop Integration Page Definition file. See Section 4.3, "Working with Page Definition Files for an Integrated Excel Workbook." Drag-and-drop components from the Bindings Palette and Components Palette. See Section 5.4, "Using the Bindings Palette" and Section 5.5, "Using the Components Palette." Double-click to edit a component. See Section 5.6, "Using the Property Inspector." Export and import Excel workbook integration metadata. See Section 5.15, "Exporting and Importing Excel Workbook Integration Metadata." Insert components in merged cells. See Section 6.1, "About ADF Desktop Integration Form-Type Components."
xv
New action, UploadAllOrNothing, which allows rows to get committed if none of the changed (or new) rows fail. See Section 7.9, "Configuring an ADF Table Component to Upload Changes Using UploadAllOrNothing Action." New feature, Explicit Worksheet Setup Action, which allows user to customize the data (or the binding container) before the client retrieves the binding container metadata. See Section 7.22, "Using Explicit Worksheet Setup Action." New property, DetailStatusMessage for ComponentAction. Section 8.2.2, "How to Invoke Component Actions in an Action Set." Visual status progress bars. See Section 8.2.5, "How to Display a Status Message While an Action Set Executes" and Section 8.2.7, "What You May Need to Know About Progress Bars." Worksheet authorization through ADF Desktop Integration page definition. See Section 11.5, "Authorizing the Excel Workbook User." Track and detect time zone change. See Section H.7, "Handling Time Zone Conversion."
Chapters now include a "Use Cases and Examples" section. All Introduction sections in chapters have been renamed to "About ..." Updated Section 3.6.1, "How to Migrate an Integrated Excel Workbook to the Current Version of ADF Desktop Integration" to include migration information while using workbooks integrated with older, or newer versions, of ADF Desktop Integration. Updated Section 3.7, "Using an Integrated Excel Workbook with Older Versions of ADF Desktop Integration" to describe compatibility of a workbook created, or updated, by a newer version of ADF Desktop Integration on a system running an older version of ADF Desktop Integration. Added a section to describe how to remove a component from integrated Excel workbook. See Section 5.14, "Removing ADF Desktop Integration Components." Revised various sections in Chapter 7, "Working with ADF Desktop Integration Table-Type Components" to: include information that a table component should not be inserted in a merged cell, and wide tables (a table with many columns) gives slow performance. See Section 7.3, "Inserting ADF Table Component into Excel Worksheet." add a custom method action that creates one or more status_initialized rows in the iterator. See Section 7.5, "Configuring a Worksheet to Download Data as Pending Insert Rows in an ADF Table component." include information that the DownloadFlaggedRows action does not apply to inserted rows. See Section 7.11.2, "Row Flagging in an ADF Table Component."
xvi
include information that the first column of the ADF Read-only Table contains important data used by the table component, and it must not be removed. See Section 7.17, "Creating an ADF Read-Only Table Component."
Added a section to describe how EL expressions for ReadOnly properties are evaluated while downloading and uploading data. See Section 7.21, "Evaluating EL Expression for ReadOnly Properties." Revised various sections in Section 8, "Adding Interactivity to Your Integrated Excel Workbook" to: document default values of the CancelButtonLabel, OKButtonLabel, or Prompt properties, if they are empty. See Section 8.2.12, "What Happens at Runtime: How the Action Set Provides a Confirmation." add a note about toolbar ribbon controls that they are shared among all open integrated workbooks. See Section 8.3.2, "How to Configure a Worksheet Command for the Runtime Ribbon Tab." include information about web pages displayed with the Dialog action that they are rendered using a .NET Web Browser control, which leverages the local Internet Explorer installation. See Section 8.4.3, "What You May Need to Know About Displaying Pages from a Fusion Web Application." add a note that evaluated EL expressions in Excel formula should not have no more than 255 characters. See Section 8.9, "Using EL Expression to Generate an Excel Formula."
Updated Section 10.2.1, "How to Register a Resource Bundle in an Integrated Excel Workbook" to add information about file extensions that they should not be included while registering a resource bundle class. Revised following sections for clarity: Section 11.1, "About Security In Your Integrated Excel Workbook" Section 13.2, "Testing Your Fusion Web Application" Section 13.4, "Testing Your Integrated Excel Workbook"
Updated Section 14.2, "Making ADF Desktop Integration Available to End Users" to update the path of adfdi-excel-runtime-client-installer.zip file. Updated Section 14.4, "Deploying a Published Workbook with Your Fusion Web Application" to describe runtime behavior after a workbook is published. Updated Table A1, Table A9, Table A11, Table A14, Table A15, Table A15, and Table A19 of Appendix A, "ADF Desktop Integration Component Properties and Actions" to add new attributes. Updated Section C.4, "Common ADF Desktop Integration Error Messages and Problems" to add more error messages. Revised Section H.1, "Installing, Upgrading, and Removing the Runtime Edition of ADF Desktop Integration" to include the fully qualified path limit of the directory where set up files of the runtime edition of ADF Desktop Integration are extracted. Added a section to describe how to upgrade the runtime edition of ADF Desktop Integration on a local system. See Section H.1.3, "How to Upgrade the Runtime Edition of ADF Desktop Integration On a Local System."
xvii
xviii
1
1
Section 1.1, "About ADF Desktop Integration" Section 1.2, "About ADF Desktop Integration with Microsoft Excel"
ADF Desktop Integration ADF Desktop Integration remote servlet ADF Model layer
1-1
For more information about ADF Desktop Integration, see the ADF Desktop Integration page on Oracle Technology Network (OTN) at: http://www.oracle.com/technetwork/developer-tools/adf/overview/i ndex-085534.html
This guide uses the term integrated Excel workbook to refer to Excel workbooks that you integrate with a Fusion web application and to distinguish these workbooks from workbooks that have not been integrated with a Fusion web application or configured with Oracle ADF functionality.
Create a Fusion web application. For information about creating a Fusion web application, see the Developing Fusion Web Applications with Oracle Application Development Framework.
Add data controls that expose the elements you require in Microsoft Excel. Create page definition files that expose the Oracle ADF bindings to use in Excel. For more information, see Section 4.3, "Working with Page Definition Files for an Integrated Excel Workbook."
Create the Excel workbooks that you intend to configure with Oracle ADF functionality. For more information, see Section 4.2, "Adding an Integrated Excel Workbook to a Fusion Web Application."
Configure the Excel workbook using the Oracle ADF bindings that you exposed in the page definition files and the Oracle ADF components that ADF Desktop Integration provides. For more information, see the following sections and chapters:
Chapter 5, "Getting Started with the Development Tools" This chapter provides an overview of the tools that ADF Desktop Integration provides to configure an Excel workbook with Oracle ADF functionality.
Chapter 6, " Working with ADF Desktop Integration Form-Type Components" This chapter describes how to insert ADF Desktop Integration form-type components into Excel worksheets and configure their properties to determine behavior at runtime.
Chapter 7, "Working with ADF Desktop Integration Table-Type Components" This chapter describes how to use the ADF Table and Read-only Table components to provide end users with a means of displaying and editing data hosted by a Fusion web application.
Chapter 12, "Adding Validation to an Integrated Excel Workbook" This chapter describes how to provide validation for your integrated Excel workbook.
Test your integrated Excel workbook. For more information, see Chapter 13, "Testing Your Integrated Excel Workbook."
After completing the integration of the Excel workbook with the Fusion web application, you deploy it to make it available to the end users. For information about this task, see Chapter 14, "Deploying Your Integrated Excel Workbook."
1-3
Providing end users with access to data and functionality hosted by a Fusion web application through a desktop interface (Microsoft Excel) that may be more familiar to them. End users can access data hosted by a Fusion web application while not connected to the application. They must log on to the Fusion web application to download data. Once data is downloaded to an Excel workbook, they can modify it while disconnected from the Fusion web application. Bulk entry and update of data may be easier to accomplish through a spreadsheet-style interface. End users can use native Excel features such as macros and calculation.
2
2
Section 2.1, "About the Summit Sample Application for ADF Desktop Integration" Section 2.2, "Setting Up and Running the Summit Sample Application for ADF Desktop Integration" Section 2.3, "Overview of the Fusion Web Application in the Summit Sample Application for ADF Desktop Integration" Section 2.4, "Overview of the Integrated Excel Workbooks in the Summit Sample Application for ADF Desktop Integration"
2.1 About the Summit Sample Application for ADF Desktop Integration
The Summit sample application for ADF Desktop Integration is a set of sample demonstrations that illustrate the main capabilities from ADF Desktop Integration. Each of the samples contain specific features that can also be identified on the developer's guide. All of the samples use the same underlying database schema which makes it very easy for accessing the source code, and also to experience the runtime behavior in a standalone way.
2.2 Setting Up and Running the Summit Sample Application for ADF Desktop Integration
Set up the development environment as described in Chapter 3, "Setting Up Your Development Environment" before you download and run the Summit sample application for ADF Desktop Integration. To download the Summit sample application for ADF Desktop Integration: 1. Download and install Oracle JDeveloper Release 12c. For more information, see Installing Oracle JDeveloper.
2.
Download the Summit sample application for ADF Desktop Integration ZIP file (SummitADF_DI1212.zip) from Oracle Technology Network.
http://www.oracle.com/pls/topic/lookup?ctx=E26099_01&id=jdevcodesamples
Setting Up and Running the Summit Sample Application for ADF Desktop Integration
3.
Download the SummitADF_Schema1212.zip file and install the Summit ADF schema. For more information, see the "How to Install the Summit ADF Schema" section in Developing Fusion Web Applications with Oracle Application Development Framework. Install ADF Desktop Integration. For more information, see Section 3.4, "Installing ADF Desktop Integration."
4.
Note:
If you have an old version of ADF Desktop Integration installed on your system, upgrade ADF Desktop Integration as described in Section 3.6, "Upgrading ADF Desktop Integration."
To run the Summit sample application for ADF Desktop Integration: 1. Extract the contents of SummitADF_DI1212.zip file to a local directory.
2.
Open the SummitADFdi.jws file in JDeveloper. This file is located in the Summit_ADFDI directory.
3. 4. 5. 6.
In the Applications window, click and expand the Model project. Open Model > Application Sources > oracle.summitdi.model > Model.jpx file. Expand the Connection group of the General tab, and click the Add icon to create a database connection. In the Create Database Connection dialog, add the connection information shown in Table 21 for your environment.
Table 21 Database Connection Properties for the Summit Sample Application for ADF Desktop Integration Property Username Password Host Name Description summit_adf summit_adf The host name for your database. For example: localhost JDBC Port The port for your database. For example: 1521 SID The SID of your database. For example: ORCL or XE
Click Test Connection to verify the connection, and then click OK to close the dialog.
7. 8. 9.
Save the Model.jpx file. Right-click Model project and choose Rebuild Model.jpr. Expand the ViewController project and choose Web Content > MainPage.jsf.
Overview of the Fusion Web Application in the Summit Sample Application for ADF Desktop Integration
2.3 Overview of the Fusion Web Application in the Summit Sample Application for ADF Desktop Integration
The Fusion web application in the Summit sample application for ADF Desktop Integration enables end users to download the integrated Excel workbooks.
2.3.1 About the Fusion Web Application in the Summit Sample Application for ADF Desktop Integration
When the end user runs the Summit sample application for ADF Desktop Integration in JDeveloper, the default browser opens the application home page. The end user can download various integrated Excel workbooks from the home page.
Figure 21 Home page of Summit Sample Application for ADF Desktop Integration
Overview of the Integrated Excel Workbooks in the Summit Sample Application for ADF Desktop Integration
Table 22 (Cont.) Integrated Excel Workbooks of Summit sample application for ADF Desktop Integration Menu Option Navigation Form Sample Editable Table with Web Picker Form and Table Quick Location Change Description Downloads EditWarehouses.xlsx workbook. Downloads EditableCusotmerSearch.xlsx workbook. Downloads WarehouseLocations.xlsx workbook.
2.4 Overview of the Integrated Excel Workbooks in the Summit Sample Application for ADF Desktop Integration
The Summit sample application for ADF Desktop Integration provides the EditCustomers.xlsx, EditWarehouses.xlsx, EditCustomerSearch.xlsx, and WarehouseLocations.xlsx integrated Excel workbooks. The EditCustomers.xlsx workbook enable end users to:
Download and view customer data in a tabular format Modify and upload the information in the workbook Upload multiple rows of data
Download and view warehouse data in a navigational format Modify and upload warehouse information in the workbook Upload the updated information immediately when user navigates to another record.
Download and view customer data in a tabular format Filter customers by Country
Download and view warehouse data and their locations in a tabular format Modify and update the region of all warehouses Upload the updated information
Subsequent sections in this chapter provide more information about the functionality in the workbooks along with cross-references to implementation details.
2.4.1 Log on to the Fusion Web Application from an Integrated Excel Workbook
At runtime, the integrated Excel workbooks in the Summit sample application for ADF Desktop Integration render an Excel ribbon tab that allows end users to log on to the Fusion web application. Figure 22 shows the runtime Warehouses tab in the Ribbon of the EditWarehouses.xlsx workbook.
Overview of the Integrated Excel Workbooks in the Summit Sample Application for ADF Desktop Integration
Each worksheet that you integrate with a Fusion web application requires an associated page definition file. For example, the Customers worksheet in the EditCustomers.xlsx workbook is associated with the ExcelCustomers.xml page definition file. In JDeveloper, expand the following nodes in the Applications window to view this file: ViewController > Application Sources > oracle.summitdi.view > pageDefs For information about how to configure a page definition file, see Section 4.3, "Working with Page Definition Files for an Integrated Excel Workbook."
The ADF Table component Download action downloads data from the Fusion web application to the worksheet. For information about how you invoke this action, see Section 7.4, "Configuring Oracle ADF Component to Download Data to an ADF Table Component." In the EditCustomers.xlsx workbook, the worksheet Startup event invokes an action set that includes the ADF Table component Download action. For information about configuring worksheet events, see Section 8.2.4, "How to Invoke an Action Set from a Worksheet Event."
For information about inserting an ADF Table component, see Section 7.3, "Inserting ADF Table Component into Excel Worksheet."
Overview of the Integrated Excel Workbooks in the Summit Sample Application for ADF Desktop Integration
For information about using Excel formulas, see Section 8.10, "Using Calculated Cells in an Integrated Excel Workbook." For information about special columns, such as Status and Changed, see Section 7.12, "Special Columns in the ADF Table Component."
3
3
Section 3.1, "About Setting Up Your Development Environment" Section 3.2, "Required Oracle ADF Modules and Third-Party Software" Section 3.3, "Configuring Excel to work with ADF Desktop Integration" Section 3.4, "Installing ADF Desktop Integration" Section 3.5, "Removing ADF Desktop Integration" Section 3.6, "Upgrading ADF Desktop Integration" Section 3.7, "Using an Integrated Excel Workbook with Older Versions of ADF Desktop Integration" Section 3.8, "Using ADF Desktop Integration on a System with Multiple Instances of JDeveloper"
Allowing ADF Desktop Integration to access Microsoft Excel Installing ADF Desktop Integration
Note:
The instructions in this guide assume that you are using Windows 7 operating system and Microsoft Excel 2007. Note that the steps might be different for different editions of Windows and Excel.
3-1
Oracle JDeveloper Install the current release of JDeveloper. ADF Desktop Integration is available as a JDeveloper feature.
Microsoft Windows Microsoft Windows operating systems support the development and deployment of Excel workbooks that integrate with Fusion web applications. For more information about supported versions of Windows, see the "Oracle JDeveloper and Application Development Framework Certification Information" page on OTN at: http://www.oracle.com/technetwork/developer-tools/jdev/index091111.html
Microsoft Excel ADF Desktop Integration supports the integration of Fusion web applications with the following types of Excel workbook: Excel Workbook The default file format for Excel workbooks is the Excel XML-based file format (.xlsx). Excel Macro-Enabled Workbook Workbooks in this format (.xlsm) use the Excel XML-based file format and can store VBA macro code. ADF Desktop Integration does not support the use of other Excel file formats. For more information about supported versions of Excel, see the "Oracle JDeveloper and Application Development Framework Certification Information" page on OTN at: http://www.oracle.com/technetwork/developer-tools/jdev/index091111.html
Note: Microsoft Excel 2003 or older versions of Microsoft Excel are not supported.
Internet Explorer Some features in ADF Desktop Integration use a web browser control from the Microsoft .NET Framework. This browser control relies on the local Internet Explorer installation to function properly. ADF Desktop Integration uses Internet Explorer to render web pages inside Excel, regardless of other browsers installed on the system or any other browser set as the default browser.
Application server For information about the application servers that you can use to deploy an application developed using ADF Desktop Integration, see the "Oracle JDeveloper
and Application Development Framework Certification Information" page on OTN at: http://www.oracle.com/technetwork/developer-tools/jdev/index091111.html
Click the Microsoft Office button, and choose Excel Options. In the Excel Options dialog, choose the Trust Center tab, and then click Trust Center Settings. In the Trust Center dialog, choose the Macro Settings tab, and then click the Trust access to the VBA project object model checkbox, as shown in Figure 31.
5.
Click OK.
For more information about securing an Excel workbook that is integrated with a Fusion web application, see Chapter 11, "Securing Your Integrated Excel Workbook."
3-3
Windows Installer 3.1 Microsoft .NET Framework The Microsoft .NET Framework 4 provides the runtime and associated files required to run applications developed to target the Microsoft .NET Framework. You can download the framework from http://www.microsoft.com/download/.
Notes:
Do not download the Client Profile edition of Microsoft .NET Framework as it is insufficient to run ADF Desktop Integration. Installation of Microsoft .NET Framework may require you to restart the system where you install it. After the restart, the setup tool automatically recommences to finalize installation.
3.
Microsoft Visual Studio 2010 Tools for Office Runtime The Microsoft Visual Studio 2010 Tools for Office Runtime (version 4) is required to run VSTO solutions for the Microsoft Office system. You can download the Microsoft Visual Studio 2010 Tools for Office Runtime from http://www.microsoft.com/download/.
4.
ADF Desktop Integration add-in You can install the ADF Desktop Integration add-in from JDeveloper, or from the setup tool provided in MW_HOME\jdeveloper\adfdi. For more information about how to set up ADF Desktop Integration, see Section 3.4.1, "How to Set Up ADF Desktop Integration." Note that the ADF Desktop Integration installation is specific to the current Windows user profile. If you have multiple Windows user profiles on your system, and you want to use ADF Desktop Integration integrated Excel workbooks from some specific user profiles, you must log in to each user profile and install the ADF Desktop Integration add-in. For more information, see Section 3.4.1, "How to Set Up ADF Desktop Integration."
Do not install both editions of ADF Desktop Integration on the same system.
Although you do not require administrator privileges to install the ADF Desktop Integration add-in, administrator privileges may be required to run the installers for additional software that the installer attempts to download and install. You should also ensure that the proxy settings for Internet Explorer are configured to allow access to *.microsoft.com because the installer attempts to automatically download missing prerequisite software from Microsoft's website. By default, the installer runs in English. You can change the language that appears by following the instructions in the "Localizing the ADF Desktop Integration Installer" section of Administering Oracle ADF Applications. Before you begin: It may be helpful to have an understanding of ADF Desktop Integration requirements. For more information, see Section 3.4, "Installing ADF Desktop Integration." To install the Designer edition of ADF Desktop Integration: Open JDeveloper. From the Tools menu, choose Install ADF Desktop Integration, as shown in Figure 32.
1. 2.
Note: The Install ADF Desktop Integration menu option is available only on the Windows installation of JDeveloper.
3.
Follow the instructions that appear in the dialog boxes to successfully install the required components. If you encounter an error during the installation process, ensure that you have removed the previous version of ADF Desktop Integration. For more information, see Section 3.5, "Removing ADF Desktop Integration."
4.
If prompted, click Yes to restart the system and complete the setup of ADF Desktop Integration.
3-5
Tip: You can also install the Designer edition of ADF Desktop Integration by running setup.exe available in the MW_ HOME\jdeveloper\adfdi\bin\excel\addin\designer directory.
If multiple instances of JDeveloper are installed, or if you have an existing instance of the ADF Desktop Integration add-in on the system, review the information in Section 3.8, "Using ADF Desktop Integration on a System with Multiple Instances of JDeveloper" before you perform the installation procedure. If you want to install the Runtime edition of ADF Desktop Integration, see Section H.1, "Installing, Upgrading, and Removing the Runtime Edition of ADF Desktop Integration."
In the Control Panel, select and open Programs and Features. Select the Oracle ADF Desktop Integration Add-in for Excel entry in the Uninstall or change a program window and click Uninstall.
Note:
If you have installed ADF Desktop Integration on multiple user profiles, you must remove it from each user profile.
Download and install the latest version of Oracle JDeveloper. Install the new version of ADF Desktop Integration. For more information, see Section 3.4, "Installing ADF Desktop Integration."
Note:
If you do not uninstall the old version of ADF Desktop Integration, an error occurs unless the new installer is in the exact same location as the old installer.
3.6.1 How to Migrate an Integrated Excel Workbook to the Current Version of ADF Desktop Integration
When you open the integrated Excel workbook after upgrading the ADF Desktop Integration add-in, the add-in detects and compares the ADF Desktop Integration version information of the workbook with the version installed on the client system. If required, you are asked to upgrade the configuration of the integrated workbook to the version installed on the client.
Note:
Integrated Excel workbooks created using an older ADF Desktop Integration client (version X) do not require migration on a system running a new version of ADF Desktop Integration client (version X+1), but integrated Excel workbooks used and saved with a newer client (version X+1) may no longer work with older clients (version X). When the integrated Excel workbook is not compatible with the installed version of the ADF Desktop Integration client, a message is displayed when you open the workbook. In such a case, you should install the newer version of the ADF Desktop Integration client in order to interact with the newer workbook.
If you are migrating your integrated Excel workbooks created using the ADF Desktop Integration client of 11.1.1.3.0 version, or older, the Migrate Workbook dialog appears confirming your action. Before you begin: It may be helpful to have an understanding of ADF Desktop Integration upgrade. For more information, see Section 3.6, "Upgrading ADF Desktop Integration." To migrate an integrated Excel workbook after upgrading: Open the integrated Excel workbook. The Migrate Workbook dialog prompts you to migrate the workbook to the current version of ADF Desktop Integration, as shown in Figure 33.
Figure 33 Migrate Workbook Dialog
1.
If you get one or more Microsoft Office Customization Installer error messages when you open the integrated Excel workbook, ignore the messages and continue. The error messages appear because ADF Desktop Integration cannot remove the old version information from the workbook before Excel detects it and reports the error.
3-7
Using an Integrated Excel Workbook with Older Versions of ADF Desktop Integration
2.
Click Yes to migrate the workbook. The ADF Desktop Integration migration process closes the workbook and then reopens it, ready to be used with the current version of ADF Desktop Integration.
3.7 Using an Integrated Excel Workbook with Older Versions of ADF Desktop Integration
When you open a workbook created, or last updated, by a newer version of ADF Desktop Integration on a system running an older version of ADF Desktop Integration, an error message is displayed if the workbook is incompatible with the installed client version. An integrated workbook and the installed ADF Desktop Integration client are incompatible if the first element of their Oracle Release number is different. For example, an integrated workbook created using version 12.1.2 of ADF Desktop Integration client is incompatible with the client from version 11.1.1.7.0.
Tip: To see the release number of the installed client and integrated workbook, examine the values of ADF Desktop Integration and Workbook Edited by Version entries in Versions tab of the About ADF Desktop Integration dialog box.
At runtime, ADF Desktop Integration ignores an incompatible workbook. The data in the workbook is not removed, but ADF Desktop Integration treats the workbook as a non-integrated workbook and the following functionalities are affected:
ADF Desktop Integration does not respond to workbook events (for example, Activate and Startup) ADF Button components do not respond to events Worksheet command buttons do not appear in the Excel Ribbon
In design mode, or test mode, the workbook continues to function as expected, but you might notice some unknown exceptions and functionality issues.
3.8 Using ADF Desktop Integration on a System with Multiple Instances of JDeveloper
There can be only one active installation of ADF Desktop Integration on a given system. By default, when you install JDeveloper, ADF Desktop Integration is extracted to MW_HOME\jdeveloper\adfdi . If you move to another version of JDeveloper installed in a different directory, you should remove the old version of ADF Desktop Integration, as described in Section 3.5, "Removing ADF Desktop Integration." You should then set up ADF Desktop Integration from the new version of JDeveloper, as described in Section 3.4, "Installing ADF Desktop Integration," to keep ADF Desktop Integration consistent with JDeveloper. Alternatively, you can set up ADF Desktop Integration in a directory that is independent of your JDeveloper installation. This approach means that you do not have to remove ADF Desktop Integration before moving to a newer version. To set up ADF Desktop Integration in an independent directory: 1. Create a directory independent of the JDeveloper installation directory. For example, you may create the following directory: D:\adfdi-excel-setup
2.
When you move to a newer version of JDeveloper, copy the contents of the following directory: MW_HOME\jdeveloper\adfdi\bin\excel\addin\designer to: D:\adfdi-excel-setup where MW_HOME is the Middleware Home directory.
3. 4. 5.
Run the setup.exe tool located in D:\adfdi-excel-setup. Follow the instructions that appear in the dialog boxes launched by setup.exe to set up the new version of ADF Desktop Integration. If prompted, click Yes to restart the system and complete the setup of ADF Desktop Integration.
WARNING: After you install ADF Desktop Integration, do not delete the directory where you copied the setup files. You can delete the files after removing ADF Desktop Integration from the system.
3-9
4
4
Section 4.1, "About Preparing Your Integrated Excel Workbooks" Section 4.2, "Adding an Integrated Excel Workbook to a Fusion Web Application" Section 4.3, "Working with Page Definition Files for an Integrated Excel Workbook" Section 4.4, "Enabling ADF Desktop Integration Manually"
Before you start, ensure that the Designer edition of ADF Desktop Integration is installed. For more information about the ADF Desktop Integration editions, see Section 3.4, "Installing ADF Desktop Integration."
4-1
In the Applications window, select the user interface project, such as ViewController, to which you want to add the new integrated Excel workbook. From the File menu, choose New > From Gallery. In the New Gallery, expand Client Tier, select ADF Desktop Integration, then Microsoft Excel Workbook, and then click OK. Figure 41 shows the New Gallery with ADF Desktop Integration category and the Microsoft Excel Workbook option.
Click OK.
5.
In the Create ADF Desktop Integration-Enabled Excel Workbook dialog, if required, edit the file name of the workbook and its location. By default, the integrated Excel workbook is saved as adfdi-workbook.xlsx in the <PROJECT_HOME>\src\excel directory of the selected project. Although you can save the workbook anywhere you choose, you should save the workbook with the other files of the Fusion web application.
6.
Click OK.
JDeveloper adds the integrated Excel workbook into the Fusion web application, and automatically enables the project with ADF Desktop Integration. Figure 42 shows the ViewController project in the Applications window.
Figure 42 adfdi-workbook.xlsx in Applications Window
If you have saved the workbook with other files of the Fusion web application, the Page Definition dialog automatically appears, as illustrated in Figure 43.
Select the page definition file for the active worksheet from the Page Definition dialog, and click OK.
If you have saved the workbook elsewhere, configure the workbook as described in Section 4.4.3, "How to Manually Configure a New Integrated Excel Workbook."
4-3
2. 3.
In the Workbook group of the Oracle ADF tab, click Workbook Properties. In the Edit Workbook Properties dialog, set or verify the values for the following properties so that you can switch between design mode and test mode as you configure the workbook:
ApplicationHomeFolder The value for this property corresponds to the absolute path for the root directory of the JDeveloper application workspace (.jws). If the workbook is located within the JDeveloper application workspace, the value of the ApplicationHomeFolder workbook property is assigned automatically.
Note:
If you are opening the Excel file after moving the application directory, ensure that the ApplicationHomeFolder property's value reflects the correct path.
Project The value for this property corresponds to the name of the JDeveloper project (.jpr) in the JDeveloper application workspace. To change the project, click the browse (...) icon and choose the project from the Project dialog, which lists the projects defined in the JDeveloper application workspace. By default, Project is set to the name of the project that contains the Excel document. ADF Desktop Integration loads the names of the available projects from the application_name.jws specified as a value for ApplicationHomeFolder.
WebAppRoot Set the value for this property to the fully qualified URL for the web context root that you want to integrate the Fusion web application with. The fully qualified URL has the following format: http://<hostname>:<portnumber>/context-root In JDeveloper, you specify the web context root (context-root) in the Java EE Application page of the Project Properties dialog. Figure 44 shows the web context root used for the Summit sample application for ADF Desktop Integration in JDeveloper and integrated Excel workbook.
Figure 44 Setting Web Context Root in JDeveloper and Integrated Excel Workbook
Note that the fully qualified URL is similar to the following if you set up a test environment on the system using the Summit sample application for ADF Desktop Integration, as shown in Figure 45. http://localhost:7101/summit
4-5
Figure 45 Home Page of Summit Sample Application for ADF Desktop Integration in a Browser
For information about how to verify that the Fusion web application is online and that it supports ADF Desktop Integration, see Section C.1, "Verifying That Your Fusion Web Application Supports ADF Desktop Integration." If you are integrating an Excel file with a secure Fusion web application, you should use the https protocol while entering the value for WebAppRoot. For more information about securing the Fusion web application, see Developing Applications with the WebLogic Security Service.
WebPagesFolder Set the value for this property to the directory that contains web pages for the Fusion web application. The directory path should be relative to the value of ApplicationHomeFolder. For example, in the EditCustomers-DT.xlsx workbook, WebPagesFolder is set to ViewController\public_html.
Figure 46 shows an example of workbook properties in the Edit Workbook Properties dialog of the Summit sample application for ADF Desktop Integration EditCustomers-DT.xlsx workbook.
4.
Click OK.
Note:
In Step 1, if the fully qualified path of the selected page definition file contains more than 259 characters, a warning message will appear when the Workbook Properties dialog is closed, and the page definition will not be loaded.
5.
In the Choose Page Definition dialog, select the page definition file. This populates the bindings palette in the ADF Desktop Integration task pane with the bindings contained in the page definition file. You can now configure the worksheet with Oracle ADF functionality.
4-7
Note:
If you get an error message Programmatic access to Visual Basic Project is not trusted when you run an integrated Excel workbook after inserting a new worksheet, enable the Trust access to the VBA project object model checkbox in Excel Options. For more information, see Section 3.3, "Configuring Excel to work with ADF Desktop Integration."
4.2.4 What Happens When You Deploy an ADF Desktop Integration-Enabled Fusion Web Application from JDeveloper
When you deploy the ADF Desktop Integration-enabled Fusion web application from JDeveloper, references to the ADF Desktop Integration shared libraries are added to the appropriate descriptor files. For any Fusion web application that contains one or more projects referencing the ADF Desktop Integration Model API library or the ADF Desktop Integration Runtime library, a platform-dependent reference to the ADF Desktop Integration Model API shared library is added during deployment. For any web application module (WAR) project that contains a reference to the ADF Desktop Integration Runtime library, a platform-dependent reference to the ADF Desktop Integration Runtime shared library is added during deployment.
The META-INF/weblogic-application.xml file of the deployed application EAR file contains a library reference to oracle.adf.desktopintegration.model. For example:
<library-ref> <library-name>oracle.adf.desktopintegration.model</library-name> </library-ref>
The WEB-INF/weblogic.xml file of the deployed web application WAR file contains a library reference to oracle.adf.desktopintegration. For example:
<library-ref> <library-name>oracle.adf.desktopintegration</library-name> </library-ref>
4.3 Working with Page Definition Files for an Integrated Excel Workbook
Page definition files define the bindings that populate the data in the Oracle ADF components at runtime. Page definition files also reference the action bindings and method action bindings that define the operations or actions to use on this data. You
must define a separate page definition file for each Excel worksheet that you are going to integrate with a Fusion web application. The integrated Excel workbook can include worksheets that do not reference page definition files. The ADF Desktop Integration task pane displays only those bindings that ADF Desktop Integration supports in the bindings palette. If a page definition file references a binding that ADF Desktop Integration does not support (for example, a graph binding), it is not displayed. Table 41 lists and describes the binding types that the ADF Desktop Integration module supports.
Table 41 Binding Requirements for ADF Desktop Integration Components
ADF Desktop Integration component ADF Input Text ADF Output Text ADF Label ADF List of Values Tree Node List ADF Button
Supported Binding Attribute binding Attribute binding Attribute and list bindings List binding
Additional comments
This ADF Desktop Integration component uses the label property of a control binding.
Tree binding attributes and Tree binding attributes must be associated list binding with a model-driven list. Various The ADF Button component in ADF Desktop Integration can invoke action sets. Action sets can reference action bindings, method action bindings, or actions exposed by components in ADF Desktop Integration. For more information about action sets, see Section 8.2, "Using Action Sets."
For information about the bindings that components in ADF Desktop Integration use, see Appendix A, "ADF Desktop Integration Component Properties and Actions." For information about the elements and attributes in page definition files, see the "pageNamePageDef.xml" section of the Developing Fusion Web Applications with Oracle Application Development Framework. For information about ADF data binding and page definition files in a Fusion web application, see the "Using ADF Model in a Fusion Web Application" chapter of the Developing Fusion Web Applications with Oracle Application Development Framework.
To create an ADF Desktop Integration page definition file: 1. Open the Fusion web application in JDeveloper.
2. 3. 4.
In the Applications window, select the user interface project, such as ViewController, to which you want to add the page definition file. From the File menu, choose New > From Gallery. In the New Gallery, expand Client Tier, select ADF Desktop Integration, then ADF Desktop Integration Page Definition, and then click OK. Figure 47 shows the New Gallery with ADF Desktop Integration category and the ADF Desktop Integration Page Definition option.
Click OK.
5. 6.
In the Create ADF Desktop Integration Page Definition dialog, if required, edit the page definition file name. Click OK.
JDeveloper adds the page definition into the Fusion web application and opens the new page definition's editor. Figure 48 shows the ViewController project with the new page definition in the Applications window.
For information about working with page definition files, see the "Working with Page Definition Files" section in the Developing Fusion Web Applications with Oracle Application Development Framework.
Remove an element in a page definition file Do not rebuild and restart the Fusion web application Or do not reload the page definition file in the integrated Excel workbook
an error message such as the following may appear when you attempt to switch a workbook to test mode:
[ADFDI-05530] unable to initialize worksheet: MyWorksheet [ADFDI-05517] unable to find control MyBindingThatWasRemoved Preparing Your Integrated Excel Workbook 4-11
Before you begin: It may be helpful to have an understanding of page definition files. For more information, see Section 4.3, "Working with Page Definition Files for an Integrated Excel Workbook." To reload page definition files in an Excel workbook: 1. Ensure that you have saved the updated page definition file in JDeveloper.
2.
In the Excel workbook, click the Refresh Bindings button in the Components group of the Oracle ADF tab. For information about the Refresh Bindings button, see Section 5.1, "About Development Tools."
After reloading the page definition file, the ADF Desktop Integration task pane of the worksheet displays the same bindings that are available in its associated page of the Fusion web application. For example, Figure 49 shows the bindings in the ExcelCustomersPageDef.xml page definition file and the same bindings in the worksheet of the EditCustomers-DT.xlsx workbook.
Figure 49 Page Definition Bindings in JDeveloper and Integrated Excel Workbook
4.3.4 What You May Need to Know About Page Definition Files in an Integrated Excel Workbook
Note the following points about page definition files in an ADF Desktop Integration project:
Integrating Multiple Excel Worksheets: You can integrate multiple worksheets in an Excel workbook with a Fusion web application. You associate a page definition file with each worksheet as described in Section 4.2.3, "How to Add Additional Worksheets to an Integrated Excel Workbook." EL Expressions in a Page Definition File: Use the following syntax to write EL expressions in a page definition file:
Dynamic (${})
Do not use the syntax Deferred (#{}) to write EL expressions. EL expressions using this syntax generate errors because they attempt to access the ADF Faces context, which is not available.
Note: EL expressions that you write for ADF Desktop Integration component in the integrated Excel workbook, such as the Input Text component, must use the Deferred (#{}) syntax.
4.4.1 How to Manually Add ADF Desktop Integration In Fusion Web Application
Use the Project Properties dialog in JDeveloper to add ADF Desktop Integration to the feature list of your project. Before you begin: It may be helpful to have an understanding of adding ADF Desktop Integration to a Fusion web application. For more information, see Section 4.4, "Enabling ADF Desktop Integration Manually." To manually add ADF Desktop Integration to your project: 1. Open the project in JDeveloper.
2.
In the Applications window, right-click the project to which you want to add ADF Desktop Integration and choose Project Properties. If the application uses the Fusion Web Application (ADF) application template, select the user interface project, such as ViewController. If the application uses another application template, select the project that corresponds to the web application.
3. 4. 5.
In the Project Properties dialog, select Features to view the list of available features. Click Add Features. In the Add Features dialog, select the ADF Desktop Integration feature and add it to the Selected list, as shown in Figure 410.
6. 7.
Click OK to close the Add Features dialog. Click OK to close the Project Properties dialog.
For more information about what happens when you add ADF Desktop Integration, see Section 4.4.4, "What Happens When You Add ADF Desktop Integration to Your JDeveloper Project."
Note: If you plan to distribute integrated Excel workbooks by adding them to ADF library files through EAR and JAR files, add ADF Library Web Application Support to your project. For more information, see Section 4.4.5, "Adding ADF Library Web Application Support."
In the Workbook group of the Oracle ADF tab, click Workbook Properties. In the Enable Workbook dialog, click Yes, as shown in Figure 411.
ADF Desktop Integration prepares your workbook, displays the ADF Desktop Integration Designer task pane, and opens the Browse For Folder dialog. For more information, see Section 4.4.3, "How to Manually Configure a New Integrated Excel Workbook."
4.
Although you can store the Excel workbooks that you integrate with Fusion web applications anywhere you choose, there are several advantages to storing them with the other files of the Fusion web application. Some of these advantages are:
Source control of the workbooks Facilitating the download of workbooks from web pages The file system folder picker that appears the first time a workbook is opened defaults to the location where you store the workbook
For example, the Summit sample application for ADF Desktop Integration stores the Excel workbooks it integrates in the following subdirectory: Summit_HOME\ViewController\src\oracle\summitdi\excel where Summit_HOME is the root directory that stores the source files for the Summit sample application for ADF Desktop Integration.
Use the Browse for Folder dialog to select the JDeveloper application home directory. In a typical JDeveloper project, the JDeveloper application home directory stores the application_name.jws file. The value you select is assigned to the ApplicationHomeFolder workbook property.
Note:
The Browse for Folder dialog does not appear if the workbook is located within the JDeveloper application workspace. In such a case, the value of the ApplicationHomeFolder workbook property is assigned automatically.
2. 3. 4. 5. 6.
In the Workbook group of the Oracle ADF tab, click Workbook Properties. In the Edit Workbook Properties dialog, configure the properties as described in Step 3 of Section 4.2.2, "How to Configure a New Integrated Excel Workbook." Click OK. In the Workbook group of the Oracle ADF tab, click Worksheet Properties. In the Edit Worksheet Properties dialog, click the browse (...) icon beside the Page Definition input field and select a page definition file from the Page Definition dialog, as shown in Figure 413.
7.
Click OK. The Excel worksheet appears with ADF Desktop Integration in the task pane. The bindings of the page definition file that you selected in Step 6, appear in the Bindings tab.
8.
By default, when you prepare a new Excel workbook with ADF Desktop Integration, it is assumed that the workbook will be integrated with an unsecure Fusion web application. If you want to integrate a workbook with a secure Fusion web application, see Chapter 11, "Securing Your Integrated Excel Workbook."
4.4.4 What Happens When You Add ADF Desktop Integration to Your JDeveloper Project
When you add the ADF Desktop Integration feature to a project, the following events occur:
The project adds the ADF Desktop Integration runtime library. This library references the following .jar files in its class path: adf-desktop-integration.jar adf-desktop-integration-model-api.jar resourcebundle.jar
The project's deployment descriptor (web.xml) is modified to include the following entries: An ADF bindings filter (adfBindings) A servlet named adfdiRemote
Note: The value for the url-pattern attribute of the servlet-mapping element for adfdiRemote must match the value of the RemoteServletPath workbook property described in Table A18.
A filter named adfdiExcelDownload A MIME mapping for Excel files (.xlsx and .xlsm)
The previous list is not exhaustive. Adding ADF Desktop Integration to a project makes other changes to web.xml. Note that some entries in web.xml are added only if they do not already appear in the file.
You should also update the include-extension-list initialization parameter to add the Excel file extensions (such as .xlsx and .xlsm), as shown in Figure 415.
For more information about web.xml, see Appendix D, "ADF Desktop Integration Settings in the Web Application Deployment Descriptor."
5
5
Section 5.1, "About Development Tools" Section 5.2, "Designer Ribbon Tab" Section 5.3, "ADF Desktop Integration Designer Task Pane" Section 5.4, "Using the Bindings Palette" Section 5.5, "Using the Components Palette" Section 5.6, "Using the Property Inspector" Section 5.7, "Using the Binding ID Picker" Section 5.8, "Using the Expression Builder" Section 5.9, "Using the Web Page Picker" Section 5.10, "Using the File System Folder Picker" Section 5.11, "Using the Page Definition Picker" Section 5.12, "Using the Collection Editors" Section 5.13, "Using the Cell Context Menu" Section 5.14, "Removing ADF Desktop Integration Components" Section 5.15, "Exporting and Importing Excel Workbook Integration Metadata"
Property Inspector Binding ID Picker Expression Builder Web Page Picker File System Folder Picker Page Definition Picker Collection Editors
ADF Desktop Integration provides two modes, design mode and the test mode, in which you can work while you configure the Excel workbook. In design mode, you use the tools provided by Oracle ADF in Excel to design and configure the integrated Excel workbook. In test mode, you can view and test the changes you made in the design mode, in the same way that the end user views the published integrated Excel workbook.
5.1.1 ADF Desktop Integration Development Tools Use Cases and Examples
You use the development tools to configure and design the integrated Excel workbook. For example, as shown in Figure 52, in EditCustomers-DT.xlsx a
5-2 Developing Applications with Oracle ADF Desktop Integration
binded ADF Table component is inserted in the integrated Excel workbook using the Customers binding from the Bindings palette.
Figure 52 ADF Desktop Integration Components and Bindings
Other ADF Desktop Integration components, such as ADF Button and ADF Label, are inserted from the Components palette, and configured using the Property Inspector and Expression Builder.
Localization: You can customize the integrated Excel workbook as part of the process to internationalize and localize with the Fusion web application. For more information, see Chapter 10, "Internationalizing Your Integrated Excel Workbook." Styles: You can configure the display of your components using several predefined Excel styles. For more information, see Section 9.2, "Working with Styles." EL Expressions: You can use EL expressions with the ADF Desktop Integration components. For more information, see Appendix B, "ADF Desktop Integration EL Expressions."
Tip: To access Oracle ADF tab from the keyboard, press Alt+C. Press the Alt key again to view the shortcut keys for Oracle ADF tab command buttons.
5-3
You can use Oracle ADF tab buttons to invoke the actions described in Table 51.
Table 51 In this group... Workbook Oracle ADF Tab Options Mode when the button is available... Design
To... Display the Edit Workbook Properties dialog to view and edit integrated Excel workbook properties. The button is also used to enable ADF Desktop Integration in a non-integrated Excel workbook.
Workbook
Display the Edit Worksheet Properties dialog to view and edit the current worksheet properties. Open the About ADF Desktop Integration dialog that provides version and property information of integrated Excel workbook. The button is also available in non-integrated Excel workbooks after ADF Desktop Integration is installed.
Design
Workbook
Design, Test
Workbook
Open the Save Workbook Design Definition as dialog that exports the current workbook definition as .xml file. Open the Choose Workbook Definition File to Import dialog that imports the workbook integration metadata from the saved .xml file. Display a dropdown list of Oracle ADF components that you can insert in the selected cell. Display the property inspector window to view and edit component properties of the selected component. Delete the selected component from the Excel worksheet. Design
Workbook
ADF Components
Design
ADF Components
Design
ADF Components
Design
Table 51 (Cont.) Oracle ADF Tab Options In this group... ADF Components Mode when the button is available... Design Reload the application workspace file (.jws) and project file (.jpr) referenced by the workbook properties of the integrated Excel workbook. Refresh all information from the page definition files used in the active integrated Excel workbook.
To...
Any modifications that you made to the page definition files in the JDeveloper project now become available in the Excel workbook. For more information, see Section 4.3.3, "How to Reload a Page Definition File in an Excel Workbook." Test Validate the Excel workbook configuration against ADF Desktop Integration validation rules. For more information about validating a workbook, see Section 13.3, "Validating the Integrated Excel Workbook Configuration." Test Switch the Excel workbook from Design design mode to test mode. This button is active only when you are in design mode. Switch the Excel workbook from Test test mode to design mode. This button is active only when you are in test mode. For more information about switching between design mode and test mode, see Section 13.4, "Testing Your Integrated Excel Workbook." Logging Display a dialog to review the client-side log entries. For more information, see Section C.3.2, "About Client-Side Logging." Display the Set Output Level dialog to choose client-side log output level. For more information, see Section C.3.2, "About Client-Side Logging." Design, Test Design
Test
Logging
Design, Test
5-5
Table 51 (Cont.) Oracle ADF Tab Options In this group... Logging Mode when the button is available...
To...
Create a new temporary logging Design, Test listener to act as a client-side log output file. For more information, see Section C.3.2, "About Client-Side Logging." Reload the ADF Desktop Integration configuration file. For more information, see Section C.3.2, "About Client-Side Logging." Publish the Excel workbook after you complete the integration between the Excel workbook and the Fusion web application. For more information about publishing an integrated Excel workbook, see Chapter 14, "Deploying Your Integrated Excel Workbook." Design, Test
Logging
Publish
Design
Tip: For quick and easy access, you can add Oracle ADF tab buttons to the Excel Quick Access toolbar.
You invoke the ADF Desktop Integration Designer task pane through launcher buttons (highlighted by the red boxes in Figure 55) available in the bottom-right corner of the Workbook and ADF Components group on the Oracle ADF tab.
Figure 55 ADF Desktop Integration Designer Task Pane Launcher Buttons
Table 52 lists the view tabs and links that appear in the task pane, provides a brief description of each item.
Table 52 Overview of ADF Desktop Integration Designer Task Pane Description Click to display the Edit Workbook Properties dialog. This dialog enables you to view and edit properties that affect the whole workbook. Examples include properties that reference the directory paths to page definition files, the URL for your Fusion web application, and so on. Click to display the Edit Worksheet Properties dialog. This dialog enables you to view and edit properties specific to the active worksheet. An example is the file name of the page definition file that you associate with the worksheet. Click to display the About dialog. This dialog provides the version and property information that can be useful when troubleshooting an integrated Excel workbook. For example, it provides information about the underlying Microsoft .NET and Oracle ADF frameworks that support an integrated Excel workbook.
Worksheet Properties
About
5-7
Integration Designer task pane. Note that the bindings palette does not display bindings that an integrated Excel workbook cannot use, so the bindings that appear may differ from those that appear in the page definition file viewed in JDeveloper.
Figure 56 Oracle ADF Bindings Palette in the ADF Desktop Integration Designer Task Pane
You use the bindings palette in design mode to insert a binding. When you attempt to insert a binding, ADF Desktop Integration inserts an Oracle ADF component that references the binding you selected. ADF Desktop Integration also prepopulates the properties of the Oracle ADF component with appropriate values. For example, if you insert a binding, such as the Commit (action) binding illustrated in Figure 56, the property inspector for an Oracle ADF Button component appears. This Oracle ADF Button component has values specified for its ClickActionSet that include invoking the Commit action binding. To insert an Oracle ADF binding, select the cell to anchor the Oracle ADF component that is going to reference the binding in the Excel worksheet, and then insert the binding in one of the following ways:
Double-click the Oracle ADF control binding you want to insert. Select the binding that you want to insert, and drag it to the desired cell. Select the control binding and click Insert Binding in the ADF Desktop Integration Designer task pane. A property inspector for the Oracle ADF component that is associated with the binding you attempt to insert appears. In some instances, you may be prompted to select one Oracle ADF component from a list of Oracle ADF components where multiple Oracle ADF components can be associated with the binding. After you select an Oracle ADF component from the list, a property inspector appears. If you choose the Oracle ADF component as ADF Input Text, ADF Output Text, or ADF Label, the binding name is assigned to the Value property. If you choose the Oracle ADF component as ADF Button or ADF Ribbon Command, the binding name is assigned to the Label property. If you choose the Oracle ADF component as ADF Table or ADF Read-only Table, the binding name is assigned to the TreeID property.
You use the components palette in design mode to insert an Oracle ADF component. First, select the cell to anchor the Oracle ADF component in the Excel worksheet, and then insert the Oracle ADF component in one of the following ways:
Double-click the Oracle ADF component you want to insert. Select the component that you want to insert, and drag it to the desired cell. Select the component and click Insert Component in the ADF Desktop Integration Designer task pane.
In all of the above cases, the Oracle ADF component's property inspector appears. Use the property inspector to specify values for the component before you complete its insertion into the Excel worksheet.
Note: The ADF Desktop Integration components are also available in the Insert Component dropdown list of Oracle ADF tab.
Select the component or binding, and click the Edit Properties icon in the Oracle ADF tab. Select the component or binding, right-click and choose Edit ADF Component Properties. Double-click the component or binding. To open property inspector of ADF Table or ADF Read-only Table, double-click any cell that is part of the table.
Getting Started with the Development Tools 5-9
Note:
ADF Button does not support the right-click or double-click action, click the button to open the property inspector dialog.
The property inspector also appears automatically after you insert an Oracle ADF binding or component into an Excel worksheet. Figure 58 shows a property inspector where you can view and edit the properties of an Oracle ADF Button component. At design time, you can edit key properties of certain Oracle ADF components by editing the Excel cell where the component appears. For example, you can edit the Value property of ADF Label and ADF Input Text components by editing the value displayed in the cell.
Note:
The property inspector does not validate that values you enter for a property or combinations of properties are valid. Invalid values may cause runtime errors. To avoid runtime errors, make sure you specify valid values for properties in the property inspector.
You can display the properties in an alphabetical list or in a list where the properties are grouped by categories such as Behavior, Data, and so on. Table 53 describes the buttons that you can use to change how properties display in the property inspector.
Table 53 Button Buttons to Configure Properties Display in Property Inspector Description Use this button to display the properties according to category.
In Figure 58, the property inspector displays the properties grouped by category.
Figure 58 Property Inspector Window for ADF Button Component
For more information about ADF Desktop Integration component properties and the bindings they support, see Appendix A, "ADF Desktop Integration Component Properties and Actions."
5-11
Table 54
Expression Builder Folders Description Lists the bindings supported in ADF Desktop Integration from the current worksheet's page definition. Lists the ADF components available in the current worksheet. Lists the resource bundles registered in Workbook.Resources along with the built-in resource bundle _ADFDIres. Lists all Excel styles defined in the current workbook. For more information, see Section 9.2, "Working with Styles.". Lists parameters defined in Workbook.Parameters. Lists the errors expression. Lists sample Excel functions that you can use with ADF Desktop Integration. For more information, see Excel's documentation.
Folder Name Bindings Components Resources Styles Workbook Worksheet Excel Functions
For more information about using the expression builder, see Section 9.3, "Applying Styles Dynamically Using EL Expressions." For information about the syntax of EL expressions in ADF Desktop Integration, and guidelines on how you write these expressions, see Appendix B, "ADF Desktop Integration EL Expressions."
For more information about displaying web pages in your integrated Excel workbook, see Section 8.4, "Displaying Web Pages from a Fusion Web Application."
ApplicationHomeFolder WebPagesFolder
The first time you open an Excel workbook the picker appears so that you can set values for the previously listed properties. For more information about opening an Excel workbook for the first time and the properties you set, see Section 4.2.2, "How to Configure a New Integrated Excel Workbook." Figure 512 shows the file system folder picker selecting a value for the ApplicationHomeFolder workbook property.
5-13
For more information about page definition files, see Section 4.3, "Working with Page Definition Files for an Integrated Excel Workbook."
5-15
Tip: Write a description in the Annotation field for each element that you add to the Edit Action dialog. The description you write appears in the Members list view and, depending on the description you write, may be more meaningful than the default entry that ADF Desktop Integration generates.
Figure 515 Context Menu Options of the ADF Output Text Component
You should use either the keyboard context menu key or the mouse's right-click button during any given session. If you use both the mouse right-click and the context menu key, the menu options may not always appear when expected. The context menu options do not appear if you select a range of cells and then invoke the context menu.
5-17
You can also remove multiple components by selecting a range of cells anchoring the components (see Figure 517), or select individual component cells using the Ctrl key, and then click the Delete ribbon button.
Figure 517 Removing Multiple ADF Desktop Integration Components
You can also remove a single component using the Delete key of the keyboard when the component origin cell is selected. You cannot remove a table component using the Delete key of the keyboard, use the Delete ribbon command instead.
To delete a component that occupies more than one cell (such as a table component, or a component in a merged cell), you need not select the entire
component. If the selected range intersects any cell of the component, it will be removed.
Do not delete cells or clear cells of the workbook if your selection includes one or more ADF Desktop Integration components. Always use the Delete ribbon command to remove a ADF Desktop Integration component. ADF Desktop Integration context menu options are not available if multiple cells are selected when the context menu is invoked.
Edit, or analyze the Excel workbook that is integrated with a Fusion web application. Using an XML editor, copy or move components between worksheets and workbooks. Copy action-set definitions between buttons or events. Perform global search and replace operations. Quickly rearrange, or copy, columns of table components.
Click Export in the Oracle ADF tab. The Save Workbook Definition As dialog box appears.
3.
Specify the file name and location of the XML file that stores the exported metadata, and click Save. ADF Desktop Integration writes the workbook definition to the specified file. In Export Workbook Metadata dialog, click OK to complete the export process.
4.
5-19
Note:
The exported XML file does not contain any native Excel settings such as named styles, named ranges, cell properties, content in unbound cells, and so on. Publishing a workbook also exports the workbook definition. For more information about publishing a workbook, see Section 14.3, "Publishing Your Integrated Excel Workbook."
After exporting the workbook definition, you can edit the XML file in any XML editor, such as JDeveloper. Figure 518 shows the workbook definition of EditCustomers-DT.xlsx in JDeveloper. While editing the workbook definition file in JDeveloper, JDeveloper automatically validates your changes against the workbook definition schema. It will display warnings that help you avoid problems later on.
Figure 518 Editing Workbook Definition in JDeveloper
To import workbook integration metadata to an integrated Excel workbook: 1. Open the integrated Excel workbook.
2.
Click Import in the Oracle ADF tab. The Choose a Workbook Definition file to Import dialog box appears.
3. 4.
Select the XML file that stores the workbook integration metadata, and click Open. In Import Workbook Metadata dialog, click OK to complete the import process.
The changes made in the workbook definition appear automatically in the integrated Excel workbook. For example, Figure 519 shows the branding value of workbook changed to Edit Customers New Workbook in the workbook definition file.
Figure 519 Editing Branding Value in the Workbook Definition
Figure 520 shows the changed branding workbook value in the Edit Workbook Properties dialog after importing the workbook definition.
Figure 520 Updated Branding Value in Edit Workbook Properties Dialog
5.15.3 What You May Need to Know About Exporting and Importing Excel Workbook Integration Metadata
The workbook integration metadata XML file uses the adfdi-workbook-definition.xsd XML schema document, which defines the XML namespace as http://xmlns.oracle.com/adf/desktopintegration/workbook. The schema is integrated into JDeveloper through the ADF Desktop Integration add-in. You can find a copy of the schema at <MW_ HOME>\jdeveloper\adfdi\etc\adfdi-workbook-definition.xsd, where MW_HOME is the Middleware Home directory.
5-21
While importing the workbook integration metadata, make a note of following points:
When the import process is initiated, the schema version number (schema-version attribute of <workbook>) of the XML file is compared against the schema version number of the installed ADF Desktop Integration client. If both values match, the workbook integration metadata is imported to the workbook. If the schema version of the XML file is lower than the schema version of the installed client, the XML file is migrated to use the installed client's schema. No prompt appears when the file is migrated, but a log of the same is maintained. If the schema version of the XML file is greater than the schema version of the installed client, the import process fails and an error message appears.
After verifying the schema version, the imported XML file is validated against the schema of the installed client. If the validation fails, the validation failure details are logged, an error is reported to the user, and the import process aborts. If the schema validation succeeds, the import process continues. If an element is missing in the imported XML file, the default value of the element is used in the integrated Excel workbook. All pre-existing worksheet and component metadata is removed before the import. If the imported worksheet's name matches an existing worksheet in the integrated workbook, that worksheet is used. Otherwise, a new worksheet is created. All non-integrated worksheets of the integrated Excel workbook are not affected by the import. If the imported component does not have valid origin information, the import process attempts to place that component on the first unused row in the target integrated worksheet. After the XML file is imported, the integrated Excel workbook's Workbook ID is replaced with the Workbook ID of the XML file. If the workbook ID is missing in the XML file, a new ID is generated.
6
6
Section 6.1, "About ADF Desktop Integration Form-Type Components" Section 6.2, "Inserting an ADF Button Component" Section 6.3, "Inserting an ADF Label Component" Section 6.4, "Inserting an ADF Input Text Component" Section 6.5, "Inserting an ADF Output Text Component" Section 6.6, "Inserting an ADF List of Values Component" Section 6.7, "Displaying Output from a Managed Bean in an ADF Component" Section 6.8, "Displaying Concatenated or Calculated Data in Components" Section 6.9, "Using Navigation Buttons"
ADF Input Text ADF Output Text ADF Label ADF List of Values ADF Button
6-1
You can insert a form component or a binding in a merged cell, or merge cells after inserting the form component or binding, but you cannot insert multiple form components in a merged cell or merge cells that are occupied by different form components. Before you insert a component in a merged cell, make a note of the following:
Drag-and-drop functionality is not supported for inserting component in a merged cell. Do not merge a component cell with non-empty cells that are above or left to it. When two or more cells are merged, Excel keeps the data and style of the most upper-left cell and discards the data of the remaining cells. So, merging a component cell with a non-empty cell above or left to itself results in the component data being overwritten. Do not merge an empty component cell that has no value or binding with empty cells above or left to it. Merging an empty component cell with empty cells above or left to itself results in the style of that component cell being overwritten. ADF Buttons do not expand to the whole merged area automatically. You can edit the Position and LowerRightCorner properties of the button to resize it as needed.
6.1.1 ADF Desktop Integration Form-Type Components Use Cases and Examples
The ADF Desktop Integration Form-type components are used to build forms in the integrated Excel workbook for user input, and output from the Fusion web application. As shown in Figure 62, the form-type components used in navigation form of EditWarehouses-DT.xlsx enable end users to navigate and update data easily.
Figure 62 Navigation Form Using ADF Desktop Integration Form-Type Components
Displaying output from a managed bean: You can use ADF Label or ADF Output Text components to display output from a managed bean. For more information, see Section 6.7, "Displaying Output from a Managed Bean in an ADF Component." Styles: You can configure the display of your form-type components using several predefined Excel styles. For more information, see Section 9.2, "Working with Styles." EL Expressions: You can use EL expressions with form-type components. For more information, see Appendix B, "ADF Desktop Integration EL Expressions."
For more information about the properties of the ADF Button component, see Section A.8, "ADF Button Component Properties." To insert an ADF Button component: 1. Open the integrated Excel workbook.
2.
Select the cell in the Excel worksheet where you want to anchor the component.
6-3
3.
In the components palette, select ADF Button and click Insert Component. Alternatively, in the Oracle ADF tab, select ADF Button from the Insert Component dropdown list. Configure properties in the property inspector to determine the actions the component invokes at runtime in addition to the appearance, design, and layout of the component. Table 61 outlines some properties you must specify values for, and provides links to additional information.
ADF Button component properties Specify... A string or an EL expression that resolves to a label at runtime to indicate the purpose of the ADF Button component. The button label defaults to the action binding ID. The EL expression, if used, references a string key in the res resource bundle. For more information about resource bundles, see Section 10.2, "Using Resource Bundles in an Integrated Excel Workbook." For more information about using labels in integrated Excel workbooks, see Section 9.4, "Using Labels in an Integrated Excel Workbook." To include the ampersand (&) character in the label, use &&. A single & character acts as a special character and is not displayed in the label.
4.
Table 61
ClickActionSet
Specify one or more actions in the Actions array of the ClickActionSet that the end user invokes when he or she clicks the ADF Button component. For more information about action sets, see Section 8.2, "Using Action Sets."
5.
Click OK. Figure 64 shows an example of the ADF Button component (in red box) at runtime.
Notes:
If you change the view mode of the Excel worksheet to the Page Layout or Page Break mode, the ADF Button components may be rendered in an unexpected position. You must return back to Normal mode without saving the workbook, and then Run and stop the integrated Excel workbook to render the buttons to their original positions. You can modify the properties of the component at a later time by selecting the cell in the worksheet that anchors the component and then displaying the property inspector. The ADF Button components are active at 100% zoom only, and are disabled when the end user zooms in or out on an integrated Excel worksheet. To remove the component, use the Delete ribbon command. For more information, see Section 5.14, "Removing ADF Desktop Integration Components."
Tip: In design mode, you can click the button, or press the spacebar when the button is in focus, to open the property inspector. The right-click context menu is disabled for a button.
If you want to add navigation buttons in your integrated Excel workbook to navigate to previous or next record, see Section 6.9, "Using Navigation Buttons."
The value that you specify for the Label property in an ADF Label component or other Oracle ADF components is evaluated after the worksheet that hosts the Oracle ADF component is initialized (opened for the first time). You can configure a number of properties for the component, such as style and position, in the worksheet using the property inspector. Figure 65 shows an ADF Label component with its property inspector in the foreground. The ADF Label component references an EL expression that resolves to the label of CountryId attribute binding at runtime.
6-5
Select the cell in the Excel worksheet where you want to anchor the component. In the components palette, select ADF Label and click Insert Component. Alternatively, in the Oracle ADF tab, select ADF Label from the Insert Component dropdown list Configure properties in the property inspector to determine the appearance, design, and layout of the component. Click OK.
4. 5.
Figure 66 shows an example of the ADF Label component (in red box) at runtime.
Figure 66 ADF Label Component at Runtime
You can modify the properties of the component at a later time by selecting the cell in the worksheet that anchors the component and then displaying the property inspector. You can also right-click in the cell and choose Edit ADF Component Properties to open the property inspector.
Note:
To remove the component, use the Delete ribbon command. For more information, see Section 5.14, "Removing ADF Desktop Integration Components."
For more information about using labels in an integrated Excel workbook, see Section 9.4, "Using Labels in an Integrated Excel Workbook."
To insert an ADF Input Text component: 1. Open the integrated Excel workbook.
2. 3.
Select the cell in the Excel worksheet where you want to anchor the component. In the components palette, select ADF Input Text and click Insert Component. Alternatively, in the Oracle ADF tab, select ADF InputText from the Insert Component dropdown list Configure properties in the property inspector to determine the appearance, layout, and behavior of the component. Table 62 outlines some properties that
Working with ADF Desktop Integration Form-Type Components 6-7
4.
you must specify values for. For information about the component's other properties, see Section A.2, "ADF Input Text Component Properties."
Table 62 ADF Input Text component properties Specify... An EL expression for the Value property to determine what binding the component references. An EL expression that resolves to False so that changes the end user makes are uploaded. Write an EL expression that resolves to True if you want the component to ignore changes. False is the default value.
5.
Click OK.
Note:
You can modify the properties of the component at a later time by selecting the cell in the worksheet that anchors the component and then displaying the property inspector. You can also right-click in the cell and choose Edit ADF Component Properties to open the property inspector. To remove the component, use the Delete ribbon command. For more information, see Section 5.14, "Removing ADF Desktop Integration Components."
Figure 68 shows an example of the ADF Input Text component (in red box) at runtime.
Figure 68 ADF Input Text Component at Runtime
You can configure a number of properties for the component such as style, behavior when a user double-clicks the cell (DoubleClickActionSet properties), and position, in the worksheet using the property inspector. Figure 69 shows an ADF Output Text component with its property inspector in the foreground.
Figure 69 ADF Output Text Component in Design Mode
To insert an ADF Output Text component: 1. Open the integrated Excel workbook.
2. 3.
Select the cell in the Excel worksheet where you want to anchor the component. In the components palette, select ADF Output Text, and click Insert Component. Alternatively, in the Oracle ADF tab, select ADF OutputText from the Insert Component dropdown list Configure properties in the property inspector to determine the appearance, layout, and behavior of the component. For example, you must write or specify an EL expression for the Value property to determine what binding the ADF Output Text component references. For more information about the values that you specify for the properties of the ADF Output Text component, see Section A.3, "ADF Output Text Component Properties."
4.
5.
Click OK. You can modify the properties of the component at a later time by selecting the cell in the worksheet that anchors the component and then displaying the property inspector. You can also right-click in the cell and choose Edit ADF Component Properties to open the property inspector.
Note:
To remove the component, use the Delete ribbon command. For more information, see Section 5.14, "Removing ADF Desktop Integration Components." Figure 610 shows an example of the ADF Output Text component (in red box) at runtime.
6-9
You can display a dropdown menu in an ADF Table component's column by selecting TreeNodeList or ModelDrivenColumnComponent as the subcomponent to create when you specify a value for the TableColumn array's InsertComponent property. For more information, see Section 7.14, "Creating a List of Values in an ADF Table Component Column." ADF List of Values components using date values are not supported.
To insert an ADF List of Values component: 1. Open the integrated Excel workbook.
2. 3.
Select the cell in the Excel worksheet where you want to anchor the component. In the components palette, select ADF List of Values and click Insert Component. Alternatively, in the Oracle ADF tab, select ADF List of Values from the Insert Component dropdown list Invoke the binding ID picker by clicking the browse (...) icon beside the input field for the ListID property and select a list binding that the page definition file exposes. Configure other properties in the property inspector to determine the appearance, design, and layout of the component. For information about ADF List of Values component properties, see Section A.5, "ADF List of Values Component Properties." Click OK.
Notes:
4.
5.
6.
You can modify the properties of the component at a later time by selecting the cell in the worksheet that anchors the component and then displaying the property inspector. You can also right-click in the cell and choose Edit ADF Component Properties to open the property inspector. To remove the component, use the Delete ribbon command. For more information, see Section 5.14, "Removing ADF Desktop Integration Components."
An Excel form cannot be configured to use ADF List of Values components that use model-driven list bindings, if the form's bound iterator is expected to contain zero rows. As a workaround, you may configure the ADF List of Values component to use a dynamic list binding instead.
Select the ADF component to display the output from the managed bean, and open its property inspector. Figure 612 shows an example where an ADF Label component is configured to display the output from an attribute binding that has its value populated by an action binding.
Figure 612 ADF Label Component That Displays Output from a Managed Bean at Runtime
3.
Write an EL expression that gets the output from a managed bean at runtime.
The example in Figure 612 shows an EL expression that retrieves the value of a string key (excel.connectionPrefix) from the res resource bundle and the value of the loggedInUser attribute binding. This attribute binding references the output from the managed bean.
4.
Click OK.
6.7.2 What Happens at Runtime: How an ADF Component Displays Output from a Managed Bean
The method action binding retrieves values from the managed bean and populates the attribute binding. The EL expression that you write retrieves the value from the attribute binding and displays it to the end user through the ADF component that you configured to display output. For example, the ADF Label component shown in design mode in Figure 613 displays a string similar to the following at runtime: Connected as sking
Figure 613 Output from a Managed Bean at Runtime
In Figure 613, sking is the user name of the user that is logged on to the Fusion web application through the integrated Excel workbook.
Before you begin: It may be helpful to have an understanding of how to display concatenated or calculated data in ADF components. For more information, see Section 6.8, "Displaying Concatenated or Calculated Data in Components." You may also find it helpful to understand functionality that can be added using other ADF Desktop Integration features. For more information, see Section 6.1.2, "Additional Functionality for ADF Desktop Integration Form-Type Components." To create an EL expression to display calculated data 1. Open the integrated Excel workbook.
2. 3. 4.
Select the ADF Input Text or ADF Output Text component to display calculated data. Open the property inspector and click the browse (...) icon of the Value property. Write an EL expression that gets the output from two, or more, expressions. Example 61 shows an EL expression that calculates the difference between the values of two fields, List Price and Cost Price, and then divides it with value of Cost Price column to generate a margin.
Click OK.
For more information about EL expressions, see Appendix B, "ADF Desktop Integration EL Expressions."
Note: If the Value property of an ADF Input Text component contains a formula, the ADF Input Text component becomes read-only at runtime regardless of the value of the ReadOnly property.
To save changes before navigating to another record, define the action sets of the button in the following order: 1. Worksheet.UpSync
2. 3. 4.
If you omit the Commit action from the action set, any pending changes to multiple records are lost when the end user's web application session ends.
To ignore changes before navigating to another record, define the action sets of the button in the following order: 1. Navigation action (for example, Next)
2.
Worksheet.DownSync
Note:
If you define button actions to ignore changes, then it is the end user's responsibility to save changes before navigating to another record.
7
7
Section 7.1, "About ADF Desktop Integration Table-Type Components" Section 7.2, "Page Definition Requirements for an ADF Table Component" Section 7.3, "Inserting ADF Table Component into Excel Worksheet" Section 7.4, "Configuring Oracle ADF Component to Download Data to an ADF Table Component" Section 7.5, "Configuring a Worksheet to Download Data as Pending Insert Rows in an ADF Table component" Section 7.6, "Configuring an ADF Table Component to Update Existing Data" Section 7.7, "Configuring an ADF Table Component to Insert Data" Section 7.8, "Configuring an ADF Component to Upload Changes from an ADF Table Component" Section 7.9, "Configuring an ADF Table Component to Upload Changes Using UploadAllOrNothing Action" Section 7.10, "Configuring an ADF Table Component to Delete Rows in the Fusion Web Application" Section 7.11, "Batch Processing in an ADF Table Component" Section 7.12, "Special Columns in the ADF Table Component" Section 7.13, "Configuring ADF Table Component Key Column" Section 7.14, "Creating a List of Values in an ADF Table Component Column" Section 7.15, "Adding a ModelDrivenColumnComponent Subcomponent to Your ADF Table Component" Section 7.16, "Adding a Dynamic Column to Your ADF Table Component" Section 7.17, "Creating an ADF Read-Only Table Component"
7-1
Section 7.18, "Limiting the Number of Rows Your Table-Type Component Downloads" Section 7.19, "Clearing the Values of Cached Attributes in an ADF Table Component" Section 7.20, "Tracking Changes in an ADF Table Component" Section 7.21, "Evaluating EL Expression for ReadOnly Properties" Section 7.22, "Using Explicit Worksheet Setup Action"
The ADF Table and ADF Read-only Table components provide end users with the functionality to download and upload rows of data. The ADF Table component also enables end users to edit or delete downloaded data, or to insert new rows of data. Figure 71 shows the ADF Table and the ADF Read-only Table components.
Figure 71 ADF Desktop Integration Table-Type Components
Each ADF Table component contains a Key column. Do not remove the Key column, as it contains important information that is used by ADF Desktop Integration for the proper functioning of the table. Removal of the Key column, or any modification in the Key column cell, results in errors and data corruption. For more information about the Key column, see Section 7.13, "Configuring ADF Table Component Key Column." The other ADF Desktop Integration components that you can use with these table-type components are described in Chapter 6, " Working with ADF Desktop Integration Form-Type Components."
7.1.1 ADF Desktop Integration Table-Type Components Use Cases and Examples
Tables are used to display the structured information. For example, Figure 72 shows an ADF Table component of Summit sample application for ADF Desktop Integration with data downloaded from the respective Fusion web application.
Change Tracking: You can enable the table component for tracking changes. For more information, see Section 7.20, "Tracking Changes in an ADF Table Component." Dependent List of Values: You can add dependent list of values components in your table component. For more information, see Section 8.8, "Creating Dependent Lists of Values in an Integrated Excel Workbook." Styles: You can configure the display of your form-type components using several predefined Excel styles. For more information, see Section 9.2, "Working with Styles." EL Expressions: You can use EL expressions with table-type components. For more information, see Appendix B, "ADF Desktop Integration EL Expressions."
Review the following sections for information about page definition file requirements specific to an ADF Table component. Before you can configure an ADF Table component to provide data-entry functionality to your end users, you must configure the underlying page definition file for the Excel worksheet with ADF bindings. For general information about the page definition file requirements for an integrated Excel workbook, see Section 4.3, "Working with Page Definition Files for an Integrated Excel Workbook." Expose the following control bindings when you create a page definition file for authoring an ADF Table component:
Tree binding that exposes the desired attribute bindings. Note that ADF Desktop Integration only supports Scrollable access mode for a ViewObject. The other access modes are not supported. Method action bindings and action bindings if you intend to configure values for the ADF Table component's RowActions and BatchOptions groups of
Working with ADF Desktop Integration Table-Type Components 7-3
properties. Examples of procedures where you set values for these groups of properties include: Section 7.3, "Inserting ADF Table Component into Excel Worksheet" Section 7.7, "Configuring an ADF Table Component to Insert Data" Section 7.5, "Configuring a Worksheet to Download Data as Pending Insert Rows in an ADF Table component"
Note:
As Excel displays a flat list of bindings and iterators are not displayed, use descriptive names for the attributes of different iterators.
Figure 73 shows the bindings that the ExcelCustomers.xml page definition file includes. This page definition file can support the use of an ADF Table component in the Excel worksheet that it is associated with.
Figure 73 ADF Bindings Supporting Use of an ADF Table Component
Before you begin: It may be helpful to have an understanding of ADF Table component. For more information, see Section 7.3, "Inserting ADF Table Component into Excel Worksheet." You may also find it helpful to understand functionality that can be added using other ADF Desktop Integration features. For more information, see Section 7.1.2, "Additional Functionality of Table-Type Components." To insert ADF Table component into Excel worksheet: 1. Open the integrated Excel workbook.
2.
Select the cell in the Excel worksheet into which you want to insert the ADF Table component. When inserting an ADF Table component, you must ensure that the data of two tables does not overlap at runtime, and the selected cell is not a merged cell.
3.
In the bindings palette of the ADF Desktop Integration Designer task pane, select the tree binding to use and click Insert Binding. Based on your selection, the Select Component dialog or the Insert Component dialog appears.
4.
In the dialog that appears, select ADF Table and click OK.
Notes:
You can also insert an ADF Table component by using the components palette or the Oracle ADF tab. Select ADF Table and click Insert Component. Alternatively, in the Oracle ADF tab, select ADF Table from the Insert Component dropdown list. If you use either the components palette or the Oracle ADF tab to create the table component, you would have to add each column manually to appear in the component at runtime. You cannot insert an ADF Table component in a merged cell. When you insert an ADF Table component using Insert Binding, then by default, InputText is defined as the subcomponent type for all columns. If you want a column to have a different subcomponent type, open the ADF Table property inspector (select any cell of the ADF Table component and click the Edit Properties button in the Oracle ADF tab), click the browse (...) icon of the Columns property. In the Edit Columns dialog, select the column, and click the browse (...) icon of the UpdateComponent property. In the Select Component dialog, select the desired subcomponent type, verify the binding and other properties, and click OK.
5.
Configure properties for the ADF Table component using the property inspector shown in Figure 74.
7-5
6.
Specify a binding expression for the attribute that uniquely identifies each row in the iterator associated with the tree binding. The UniqueAttribute property may be left blank if the binding's iterator supports row keys. Configure the BatchOptions properties of the ADF Table component as described in Table 71.
BatchOptions Properties of the ADF Table Component This value... The Commit action binding that the page definition file exposes.
7.
Table 71
Optionally, configure the RowLimit group of properties to determine what number of rows the ADF Table component can download. For more information, see Section 7.18, "Limiting the Number of Rows Your Table-Type Component Downloads."
9.
Click OK.
For more information about the properties that you can set for the ADF Table component, see Section A.9, "ADF Table Component Properties and Actions." To remove the table component, use the Delete ribbon command. For more information, see Section 5.14, "Removing ADF Desktop Integration Components."
Select the cell in the Excel worksheet that references the ADF Table component and click the Edit Properties button in the Oracle ADF tab. In the Edit Component: ADF Table dialog, click the browse (...) icon of the Columns property. The Edit Columns dialog appears, listing all the columns of the selected ADF Table component.
4.
Click Add to add a new column. The new column is inserted at the end of the Members list. To move the column to a specific position, select the column and use the Up and Down arrow keys. Configure the new column's properties in the right pane of the dialog. Click OK.
Note:
5. 6.
If you have not moved the new column as described in Step 4, it appears as the last column of the table.
ADF Desktop Integration does not limit the number of columns you can add in an ADF Table component you can add as many columns as your version of Excel supports. However, it has been observed that a very wide table gives slow performance and poor user experience. If you experience the same, you must try reducing the number of columns of the table before diagnosing other reasons for slow performance.
Working with ADF Desktop Integration Table-Type Components 7-7
7.4 Configuring Oracle ADF Component to Download Data to an ADF Table Component
After you add an ADF Table component to a worksheet, you configure it and the worksheet that hosts it, so that the ADF Table component downloads data from the Fusion web application. To achieve this, you configure an Oracle ADF component, such as a worksheet ribbon command, to invoke an action set. The action set that is invoked must include the ADF Table component Download action among the actions that it invokes. The number of rows that an ADF Table or an ADF Read-only Table component contains expands or contracts based on the number of rows to download from a Fusion web application. You should not place anything to the left or right of a table-type component unless you want to replicate it when Excel inserts rows to accommodate the data that one of the table-type components downloads. You can place other components above or below a table-type component as they maintain their position relative to the table-type component at runtime. End users who want to insert new rows of data into an ADF Table component at runtime must insert full rows into the Excel worksheet that hosts the ADF Table component.
7.4.1 How to Configure an ADF Component to Download Data to an ADF Table Component
Configure an Oracle ADF component, a worksheet ribbon button, or a worksheet event to invoke an action set that, in turn, invokes the ADF Table component Download action. Before you begin: You may also find it helpful to understand functionality that can be added using other ADF Desktop Integration features. For more information, see Section 7.1.2, "Additional Functionality of Table-Type Components." It may be helpful to have an understanding of how to configure ADF component to download data to an ADF Table data component. For more information, see Section 7.4, "Configuring Oracle ADF Component to Download Data to an ADF Table Component." To configure an ADF component to download data to an ADF Table component: 1. Open the integrated Excel workbook.
2.
Click the Worksheet Properties button in the Oracle ADF tab, and add a ribbon command. For more information about adding a ribbon command in a worksheet, see Section 8.3.1, "How to Define a Workbook Command Button for the Runtime Ribbon Tab."
Note:
Instead of adding a ribbon command, you can configure a worksheet event or an Oracle ADF component (a button, for example) to invoke the action set at runtime.
3. 4.
Open the Edit Action dialog to configure an action set. For more information about invoking action sets, see Section 8.2, "Using Action Sets." Add the ADF Table component Download action to the list of actions that the action set invokes at runtime. Note that Download is a component action.
The ADF Table component Download action downloads the current state of the binding referenced by the ADF Table component TreeID property. To ensure that the state of this binding is up to date before download, add a query action that refreshes the binding before the action set invokes the ADF Table component Download action. Figure 77 shows the Edit Action dialog in the EditCustomers-DT.xlsx workbook where the action set invoked by the worksheet event Startup is configured.
Figure 77 Action Set Downloading Data to an ADF Table Component
5.
Click OK.
7.4.2 What Happens at Runtime: How the ADF Table Component Downloads Data
The end user invokes the action set that you configured. The action set invokes the list of actions specified in order. These include an action that invokes the Download action of the ADF Table component. When invoked, the Download action downloads all rows from the tree binding referenced by the ADF Table component TreeID property. Make a note of following key points when the Download action is invoked at runtime:
If there are any rows marked as changed when the Download action is invoked, the end user is prompted to confirm the action and to continue (see Figure 78). If the end user chooses No, the action and the action set are cancelled without error.
Working with ADF Desktop Integration Table-Type Components 7-9
Configuring a Worksheet to Download Data as Pending Insert Rows in an ADF Table component
All existing Excel rows are removed from the table in Excel. The status column is cleared of all messages.
The number of rows that the action downloads depends on the values set for the RowLimit group of properties in the ADF Table component. For more information, see Section 7.18, "Limiting the Number of Rows Your Table-Type Component Downloads."
Note:
Any filter criteria that has been applied to the worksheet automatically gets cleared prior to the Download action.
7.5 Configuring a Worksheet to Download Data as Pending Insert Rows in an ADF Table component
A Pending Insert row is a worksheet table row with data that, on upload, is inserted as a new data row in the iterator. For example, if the end user creates a new row in the table by using the Insert option in the right click context menu, the new row is treated as a pending insert row and is inserted to the iterator when being uploaded. A Pending Update row is a worksheet table row with data that, on upload, updates an existing data row in the iterator. For example, if the iterator of the tree binding contains some rows retrieved from the database and when these rows are downloaded to the ADF table, they are treated as pending update rows. If the end user makes changes to these rows and uploads them, the existing rows in the iterator are updated with new values from the ADF Table row. In most cases, rows in the iterator of the tree binding are downloaded as pending update rows into the ADF Table. If you want some rows to be downloaded as pending inserts, you need to set the state of these rows to STATUS_INITIALIZED. For more information about how to set a row's state as STATUS_INITIALIZED, see the setNewRowState method in Oracle Fusion Middleware Java API Reference for Oracle ADF Model. Note the following differences between pending insert rows and pending update rows:
Pending insert rows are populated with the value of the EL expression for the insert component that is associated with each column in the ADF Table component, while pending update rows are populated with the value of the EL
expression for the update component that is associated with each column in the ADF Table component.
When evaluated for pending insert rows, the EL expression #{components.componentID.currentRowMode} returns Insert. In contrast, the same EL expression returns Update for pending update rows. Note that the componentID part of the EL expression #{components.componentID.currentRowMode} references the ID of the ADF Table component.
If InsertRowEnabled is set to False, any changes to the downloaded STATUS_INITIALIZED rows are ignored when upload is performed.
7-11
7.6.2 What Happens at Runtime: How the ADF Table Component Updates Data
When the end user changes data in a row, ADF Desktop Integration marks the row and an upward pointing triangle appears in a row of the _ADF_ChangedColumn column. After updating the existing data, the end user initiates the upload process to save the changes. For more information about the ADF Table component's upload process, see Section 7.8, "Configuring an ADF Component to Upload Changes from an ADF Table Component." Excel uploads modified rows from the integrated workbook in batches rather than row by row. You can configure the size of batches and the actions an ADF Table component invokes when it uploads a batch. For more information about batch processing, see Section 7.11, "Batch Processing in an ADF Table Component." For more information about the properties that you can set for the ADF Table component, see Section A.9, "ADF Table Component Properties and Actions."
Note:
Any filter criteria that has been applied to the worksheet is automatically cleared prior to the upload action.
7.7.1 How to Configure an ADF Table Component to Insert Data Using a View Object's Operations
If you want the changes that the end user makes in an ADF Table component to be committed invoking the ADF Table component's Upload action, you must configure some of the ADF Table component's properties. Before you begin: It may be helpful to have an understanding of how to configure ADF Table component to insert data. For more information, see Section 7.7, "Configuring an ADF Table Component to Insert Data." You may also find it helpful to understand functionality that can be added using other ADF Desktop Integration features. For more information, see Section 7.1.2, "Additional Functionality of Table-Type Components." To configure an ADF Table component to insert data using a view object's operations: 1. Open the project in JDeveloper.
2.
If not present, add a CreateInsert and a Commit action binding to the page definition file that is associated with the Excel worksheet that hosts the ADF Table component. For more information, see Section 4.3, "Working with Page Definition Files for an Integrated Excel Workbook" and Section 7.2, "Page Definition Requirements for an ADF Table Component."
3. 4. 5.
Open the integrated Excel workbook. Select the cell in the Excel worksheet that references the ADF Table component and click the Edit Properties button in the Oracle ADF tab. In the Edit Component: ADF Table dialog, configure the RowActions properties of the ADF Table component as described in the Table 73:
RowActions properties of ADF Table component This value... True
Table 73
InsertBeforeRowAction The CreateInsert action binding that the page definition file ID exposes. InsertRowsAfterUpload True, to upload the inserted rows again regardless of whether Enabled they have been previously uploaded. By default, this property is set to False. The property is ignored if InsertRowEnabled is set to False.
7-13
6.
Configure the BatchOptions properties of the ADF Table component as described in the Table 74.
BatchOptions Properties of the ADF Table Component This value... The Commit action binding that the page definition file exposes.
Table 74
Configure the Columns property of the ADF Table component as described in the Table 75.
Columns property of ADF Table component This value... True
Table 75
Set the Value field of the UpdateComponent property to the update attribute from the page definition file. For example, #{row.bindings.ProductId.inputValue}. Verify that ReadOnly property of UpdateComponent is set appropriately. This property only appears if you selected InputText or TreeNodeList as the subcomponent to associate with the column. Set ReadOnly to False if you do want users to edit the values in the column, set to True otherwise. For more information about the components that you can use as a subcomponent, see Chapter 6, " Working with ADF Desktop Integration Form-Type Components."
ID
Set a value in this field that uniquely identifies the column in the ADF Table component's list of columns. A value for this property is required. The ADF Table component generates an initial value that you need not modify. Set this property to a style defined in the workbook or to an EL expression that applies a style to the cells in the column at runtime. For more information about styles, see Chapter 9, "Configuring the Appearance of an Integrated Excel Workbook." Set this property to a label or to an EL expression that evaluates to a label which is rendered in the column header at runtime. For more information about labels, see Section 9.4, "Using Labels in an Integrated Excel Workbook." Set this property to a style defined in the workbook or to an EL expression that applies a style to the column's header cell at runtime. For more information about styles, see Chapter 9, "Configuring the Appearance of an Integrated Excel Workbook."
CellStyleName
HeaderLabel
HeaderStyleName
8.
Repeat Step 7 for each column that contains data to commit during invocation of the Upload action. For information about ADF Table component properties, see Section A.9, "ADF Table Component Properties and Actions."
Notes:
If you are using a polymorphic view object and want to insert a new row, the default CreateInsert action binding is not sufficient. You must create a custom method that also sets the discriminator value in the newly created row. While creating the custom method, you must expose the custom method as an action binding in the page definition file. The action binding must be specified as the InsertBeforeActionId rather than CreateInsert.
If the InsertRowsAfterUploadEnabled property is set to False and the end user tries to upload the inserted rows again, an error message in the status column is displayed indicating that the row cannot be inserted more than once.
7.8 Configuring an ADF Component to Upload Changes from an ADF Table Component
You configure the ADF Table component and the worksheet that hosts it so that end user can upload changes they make to data in the ADF Table component to the Fusion web application. To configure this functionality, you decide what user gesture or worksheet event invokes the action set that invokes the ADF Table component's Upload action. The Upload action commits all successful rows even when some rows have failures. Use the UploadAllOrNothing action instead if you want no row changes to get committed if one, or more, row failures occur (see Section 7.9, "Configuring an ADF Table Component to Upload Changes Using UploadAllOrNothing Action"). To provide upload options to end users in a web page from the Fusion web application that differ from the default upload dialog, you must specify a Dialog action in the action set before the action that invokes the ADF Table Component's Upload action. For more information, see Section 7.8.5, "How to Create a Custom Upload Dialog."
Note:
In a master-detail relationship, ADF Desktop Integration does not support editing of the ViewLink source attributes, as the selections in the child view object would change as a result. To prevent any accidental editing, define the ViewLink source attributes to be read-only, or use a model configuration that does not include a view link between master and detail.
7.8.1 How to Configure an ADF Component to Upload Data from an ADF Table Component
Configure an ADF component, such as a worksheet ribbon command, to invoke an action set that, in turn, invokes the ADF Table component Upload action. Before you begin: It may be helpful to have an understanding of how to configure ADF component to upload data from an ADF Table data component. For more information, see Section 7.8, "Configuring an ADF Component to Upload Changes from an ADF Table Component."
7-15
You may also find it helpful to understand functionality that can be added using other ADF Desktop Integration features. For more information, see Section 7.1.2, "Additional Functionality of Table-Type Components." To configure an ADF component to upload changed data from an ADF Table component: 1. Open the integrated Excel workbook.
2.
Open the Edit Action dialog to configure the action set that invokes the ADF Table component Upload action. For more information about action sets, see Section 8.2, "Using Action Sets."
3.
Add the ADF Table component Upload action to the list of actions that the action set invokes at runtime. Figure 710 shows the Edit Actions dialog in the EditCustomers-DT.xlsx workbook, where the action set invoked by the ribbon command labeled Upload at runtime is configured.
Figure 710 Action Set Uploading Data from an ADF Table Component
4.
Click OK.
Note:
The action set does not include a call to a commit-type action as the ADF Table component's batch options already include calls to Commit. For more information, see Section 7.11.1, "How to Configure Batch Options for an ADF Table Component."
7.8.2 What Happens at Runtime: How the ADF Table Component Uploads Data
At runtime, the end user invokes the action set through whatever mechanism you configured (ADF component, worksheet ribbon button, worksheet event). This triggers the following sequence of events:
1.
If the ADF Table component contains dynamic columns, ADF Desktop Integration verifies whether the dynamic columns that were expanded the last time the ADF Table component's Download action was invoked are still present in the Fusion web application. If the columns are not present, ADF Desktop Integration prompts the end user to determine whether to continue upload process. If the end user decides not to continue, ADF Desktop Integration returns an abort code to the executing action set. If the ADF Table component contains no pending changes to upload, the ADF Table component's Upload action returns a success code to the executing action set. If you did not configure a custom upload dialog for the action set, as described in Section 7.8.5, "How to Create a Custom Upload Dialog," ADF Desktop Integration presents the default upload dialog shown in Figure 711.
2.
3.
If the end user clicks Cancel, ADF Desktop Integration returns an abort code to the executing action set. If the end user clicks OK, the action set continues executing with the options specified in the dialog for the upload operation.
4.
The ADF Table component uploads modified rows in batches, rather than row by row. You can configure the batch options using the BatchOptions group of properties. For more information about batch options for the ADF Table component, see Section 7.11, "Batch Processing in an ADF Table Component." Each row of a batch is processed in the following way, and the process continues until all changed rows of each batch are processed:
a. b. c. d.
For inserted rows, invoke the InsertBeforeRowActionID action, if specified. Set attributes from the worksheet into the model, including any cached row attribute values. For edited rows, invoke the UpdateRowActionID action; and for inserted rows, invoke the InsertAfterRowActionID action, if specified. For each uploaded row, displays a status message in the Status column. For more information, see Section 8.2.5, "How to Display a Status Message While an Action Set Executes." For any row failure, it verifies the value of AbortOnFail. If AbortOnFail is set to False, it continues upload process, otherwise it stops uploading data and invokes the commit action.
e.
5.
While uploading data, the ADF Table component returns a success or failure code to the executing action set based on the following:
Working with ADF Desktop Integration Table-Type Components 7-17
If the ADF Table component uploads all batches successfully, it returns the success status to the executing action set. If the end user has selected the Download all rows after successful upload option in Step 3, the ADF Table component then downloads all rows from the Fusion web application. If the ADF Table component did not upload all batches successfully, the action set invokes the action specified by the RowActions.FailureActionID property, if an action is specified for this property. ADF Desktop Integration returns a failure code to the action set.
If you selected On failure, continue to upload subsequent rows in the Upload Options dialog of Step 3, the Upload action returns a success code to the action set even if some individual rows encountered validation failures.
Note:
If an ADF Table component column's ReadOnly property evaluates to True, the ADF Table component's Upload action ignores changes in the column's cells. For more information about an ADF Table component column's properties, see Table A10.
7.8.3 What Happens at Runtime: How the ReadOnly EL Expression Is Evaluated During Upload
At runtime, if an ADF Table component column's ReadOnly property evaluates to True, the ADF Table component's Upload action ignores all changes in the column's cells. For more information about change tracking, see Section 7.21, "Evaluating EL Expression for ReadOnly Properties."
Invokes configured actions, applies row attribute value changes, and performs data validation. In case of any error, reverts back to the savepoint state.
Note:
A second iteration is performed, if required, to re-upload any successfully uploaded rows whose changes were reverted due to a subsequent upload error.
For more information about savepoints, see the "Using Trees to Display Master-Detail Objects" section in the Developing Fusion Web Applications with Oracle Application Development Framework.
In addition to the ADFdi_CloseWindow element (for example, a span element) described in Section 8.4, "Displaying Web Pages from a Fusion Web Application," the page that you create in Step 1 must include the elements described in Table 76.
Span Elements Required for Custom Upload Description If you set this element to True, the action set stops uploading if it encounters a failure. If the element references False, the action set attempts to upload all rows and indicates if each row succeeded or failed to upload. Set this element to True so the action set downloads data from the Fusion web application to the ADF Table component after the action set uploads modified data.
Table 76 Name
ADFdi_ AbortUploadOnFailure
ADFdi_ DownLoadAfterUpload
Note:
The page you create must include both elements to prevent ADF Desktop Integration presenting the default upload dialog to end users.
3.
Add a Dialog action to invoke the page you created in Step 1 before the action in the action set that invokes the ADF Table component's Upload action. For more information about displaying pages from a Fusion web application, see Section 8.4, "Displaying Web Pages from a Fusion Web Application."
7-19
Note:
If there is no server connectivity when the end user tries to upload data, the end user gets an error when the Dialog action fails to find the custom upload page. ADF Desktop Integration does not revert to the standard dialog when server connectivity is not available.
For more information about displaying a page from the Fusion web application, see Section 8.4, "Displaying Web Pages from a Fusion Web Application." Otherwise, the runtime behavior of the action set that you configure to upload data is as described in Section 7.8.2, "What Happens at Runtime: How the ADF Table Component Uploads Data."
7.9 Configuring an ADF Table Component to Upload Changes Using UploadAllOrNothing Action
ADF Desktop Integration commits all row changes that are successfully uploaded during a Table.Upload operation, even when one or more rows has failures. For example, if 100 rows are uploaded and only three rows contain failures, 97 rows are still committed to the database. For more information, see Section 7.8, "Configuring an ADF Component to Upload Changes from an ADF Table Component." Using the UploadAllOrNothing action, you can configure the upload process to commit all changed rows only if all rows are successfully uploaded. For example, if 100 rows are uploaded, and if any row fails, no rows are committed to the database.
Open the Edit Action dialog to configure the action set that invokes the ADF Table component actions. For more information about action sets, see Section 8.2, "Using Action Sets."
3. 4.
Add the ADF Table component UploadAllOrNothing action to the list of actions that the action set invokes at runtime. Click OK.
Configuring an ADF Table Component to Delete Rows in the Fusion Web Application
During the UploadAllOrNothing action, ADF Desktop Integration uploads all changed worksheet rows prior to invoking specified by CommitBatchActionID. If one, or more, row-level failures occur, the action specified by FailureActionID is invoked and the action specified by CommitBatchActionID is not invoked. In the event of a failure, all changed column values remain unchanged. The status column indicates failure for all row-level failures, but remains empty for all rows without errors. When all rows succeed and are successfully committed, the changed column values are cleared and the status column for the uploaded rows reports success.
Notes:
The UploadAllOrNothing action is only supported for DataControls that support database transactions. If CommitBatchActionID is not configured and an action set contains the UploadAllOrNothing action, a validation error is reported.
7.9.3 Limiting the Amount of Changed Data That Can Be Uploaded With UploadAllOrNothing Action
Uploading a very large number of changed worksheet rows with the UploadAllOrNothing action could result in significant memory consumption on the application server. To prevent end users from uploading too much data during the UploadAllOrNothing action, set the UploadAllOrNothing.ChangedDataLimit servlet parameter (specified in Kb) to limit the total amount of changed data that can get uploaded. If no parameter value is specified, a default limit of 10,240 Kb is used. If the total amount of changed data uploaded exceeds the UploadAllOrNothing.ChangedDataLimit value, an error message is reported to the end user, and the UploadAllOrNothing action is aborted. Note that the action specified by Table.RowActions.FailureActionID is invoked when the changed data limit is exceeded.
7.10 Configuring an ADF Table Component to Delete Rows in the Fusion Web Application
The ADF Table component exposes an action (DeleteFlaggedRows) that, when invoked, deletes the rows in the Fusion web application that correspond to the flagged rows in the ADF Table component. A flagged row in an ADF Table component is a row where the end user has double-clicked or typed a character in the cell of the _ADF_ FlagColumn column as described in Section 7.11, "Batch Processing in an ADF Table
Working with ADF Desktop Integration Table-Type Components 7-21
Configuring an ADF Table Component to Delete Rows in the Fusion Web Application
Component." The _ADF_FlagColumn column must be present in the ADF Table component to configure it to delete rows in the Fusion web application. In addition, the page definition file that you associate with the worksheet that hosts the ADF Table component must expose a Delete action binding.
7.10.1 How to Configure an ADF Table Component to Delete Rows in the Fusion Web Application
To delete rows from an ADF Table component, you must add the Delete action binding to the page definition file, configure RowActions group of properties of the ADF Table component, and configure an action set to invoke the DeleteFlaggedRows action. Before you begin: It may be helpful to have an understanding of how to configure ADF Table component to delete data rows in Fusion web application. For more information, see Section 7.10, "Configuring an ADF Table Component to Delete Rows in the Fusion Web Application." You may also find it helpful to understand functionality that can be added using other ADF Desktop Integration features. For more information, see Section 7.1.2, "Additional Functionality of Table-Type Components." To configure an ADF Table component to delete rows in a Fusion web application: 1. Open your Fusion web application in JDeveloper.
2.
If not present, add a Delete action binding to the page definition file that is associated with the Excel worksheet that hosts the ADF Table component. For more information, see Section 4.3, "Working with Page Definition Files for an Integrated Excel Workbook."
3.
Open the property inspector for the ADF Table component and set values for the RowActions group of properties as described in Table 77.
RowActions Properties of ADF Table component To... The Delete action binding that the page definition file exposes. True to enable the ADF Table component to delete rows in the Fusion web application. False is the default value.
Table 77
For more information about ADF Table component properties, see Section A.9, "ADF Table Component Properties and Actions."
4. 5. 6.
Click OK. Open the integrated Excel workbook. Open the Edit Action dialog to configure an action set for the Oracle ADF component, ribbon control, or worksheet event that the end user uses to invoke the action set at runtime. Add the ADF Table component's DeleteFlaggedRows action to the list of actions that the action set invokes at runtime.
7.
Configuring an ADF Table Component to Delete Rows in the Fusion Web Application
For more information about invoking action sets, see Section 8.2, "Using Action Sets."
8.
Click OK.
Note: Add the DeleteFlaggedRows action in a separate action set and do not include it with other table actions like Download or Upload.
7.10.2 What Happens at Runtime: How the ADF Table Component Deletes Rows in a Fusion Web Application
The end user flags rows to delete, as described in Section 7.11.2, "Row Flagging in an ADF Table Component." The end user then invokes the action set. The following sequence of events occurs:
1.
If specified, the action binding referenced by the BatchOptions.StartBatchActionID property is invoked. Failures from this step are treated as errors. An error stops the action set invoking. It also returns the error condition to the action set. If an action binding is specified for the ActionSet.FailureActionID property, the action set invokes the specified action binding. For more information about configuring batch options, see Section 7.11, "Batch Processing in an ADF Table Component."
2.
The action set invokes the Delete action binding specified by RowActions.DeleteRowActionID.
Note:
Rows inserted since the last invocation of the ADF Table component's Download action but not uploaded to the Fusion web application are ignored even if flagged for deletion.
3.
If no errors occur during the invocation of the Delete action binding, a success message entry appears in the _ADF_StatusColumn column. If a failure occurs, the ADF Table component stops invocation of the Delete action binding and continues to Step 4. If an action binding is specified for the BatchOptions.CommitBatchActionID property, the action set invokes it. If this step fails, the action set stops processing batches. If no failures occur, the action set processes the next batch by invoking the action binding specified by the BatchOptions.StartBatchActionID property, and so on until the action set processes all batches. If the action set processes all batches successfully, it invokes the action binding specified by its ActionOptions.SuccessActionID property if an action binding is specified for this property. It then removes the rows deleted in the Fusion web application by invocation of the Delete action binding specified by RowActions.DeleteRowActionID from the worksheet and returns a success code to the action set. If failures occur while the action set processes the batches, the action set invokes the action binding specified by its ActionOptions.FailureActionID property if an action binding is specified for this property. This action binding returns a failure code to the action set.
4.
5.
7-23
6.
If an unexpected exception occurs while the action set invokes its actions, an error code is returned to the action set. All row-level errors are displayed in the Status column, and all batch-level errors can be tracked through Table.errors. For more information about error handling, see Section 12.4, "Error Reporting in an Integrated Excel Workbook."
Select the cell in the Excel worksheet that references the ADF Table component, and then click the Edit Properties button in the Oracle ADF tab. Set values for the BatchOptions group of properties in the property inspector that appears.
RowData.BatchOptions Properties To... Specify how many rows to process before an ADF Table component action (Upload or DeleteFlaggedRows) invokes the action binding specified by CommitBatchActionID. Any value other than a positive integer results in all rows being processed in a single batch. The default value is 100 rows. The action binding to invoke after the ADF Table component processes each batch. Typically, this is the Commit action binding. True When True, the ADF Table component processes rows in batches determined by the value of BatchSize. When False, the ADF Table component uploads all modified rows in a single batch. True is the default value.
Table 78
CommitBatchActionID
LimitBatchSize
Table 78 (Cont.) RowData.BatchOptions Properties Set this property... StartBatchActionID To... Specify the action binding to invoke at the beginning of each batch.
4.
Click OK.
Note that a failure at the entity-level is not considered a batch failure. A failure at the commit level (for example, a wrong value for a foreign key attribute) is considered a batch failure.
Note:
By default, the solid circle character indicates a row flagged for flagged-row processing. However, any nonempty cell in a _ADF_ FlagColumn column flags the corresponding row for flagged-row processing.
DeleteFlaggedRows DownloadFlaggedRows
You can use the FlagAllRows component action to flag all rows, and the UnflagAllRows component action to unflag all rows of the ADF Table component.
Notes:
The ADF Table component's DownloadFlaggedRows action does not support changes in table column structure after the last invocation of the Download or DownloadForInsert action. The table column structure usually changes if you are using dynamic columns, or if the table contains columns with complex expressions in the Visible property. The DownloadFlaggedRows action is not applicable to inserted rows.
7-25
Use of these component actions is dependent on the appearance of the _ADF_ FlagColumn column in the ADF Table component. If you remove the _ADF_ FlagColumn column from the ADF Table component, you cannot invoke any of these component actions. For more information about these component actions, see Section A.9.3, "ADF Table Component Actions." At runtime, the end user can invoke any of the previously listed component actions from an action set. The invoked component action processes all flagged rows. For example, it downloads or deletes all flagged rows. For more information about configuring an action set to invoke a component action, see Section 8.2.2, "How to Invoke Component Actions in an Action Set."
It is important that the commit exception gets thrown again after rollback so that the commit errors are reported as expected on the client.
_ADF_ChangedColumn The cells in this column track changes to the rows in the ADF Table component. If a change has been made to data in a row of the ADF Table component since download or the last successful upload, a character that resembles an upward pointing arrow appears in the corresponding cell of the _ADF_ChangedColumn column. This character toggles (appears or disappears) when a user double-clicks a cell in this column. Figure 713 shows an example.
Note:
If the end user does not want the ADF Table component's Upload action to upload changes in the rows flagged by this column, the user must clear the entry that appears in the corresponding cell.
A confirmation dialog appears to end users when the ADF Table component's Download action is invoked, and one or more rows in this column are flagged as changed. The end user clicks OK to allow the Download action to execute, or Cancel to stop the execution of the Download action.
_ADF_FlagColumn When the end user double-clicks a cell in this column, the corresponding row is flagged for flagged-row processing. A solid circle character appears to indicate that the row is flagged for flagged-row processing. For more information about the use of this column, see Section 7.11.2, "Row Flagging in an ADF Table Component." A confirmation dialog appears to end users when the ADF Table component's DownloadFlaggedRows action is invoked, and one or more rows in _ ADFChangedColumn and _ADF_FlagColumn are flagged. The end user clicks OK to allow the action to execute or Cancel to stop the execution of the action.
Note:
By default, the solid circle character indicates a row flagged for flagged-row processing. However, any nonempty cell in a _ADF_ FlagColumn flags the corresponding row for flagged-row processing.
_ADF_StatusColumn This column reports the results of invocation of the following ADF Table component actions: DeleteFlaggedRows Upload
A message appears in the cell of the _ADF_StatusColumn to indicate the result of the invocation for the corresponding row. If the end user invokes a DoubleClickActionSet defined in an ADF Table column and an error occurs, the errors are also reported in the status column of the corresponding row. Figure 714 shows an example of Status column message.
Figure 714 Status Column in an ADF Table Component
_ADF_RowKeyColumn This column, also referred to as the Key column, contains important information about the ADF Table component used by ADF Desktop Integration at runtime. The column appears both at runtime and design time. You can remove the column from the table at design time, but note that it automatically appears at runtime as the last column of the table. For more information about the _ADF_RowKeyColumn, see Section 7.13, "Configuring ADF Table Component Key Column."
7-27
The ADF Table component treats the properties of the _ADF_ChangedColumn, _ADF_ FlagColumn, _ADF_RowKeyColumn, and _ADF_StatusColumn columns differently from the properties of other columns that it references. It ignores the values set for properties such as InsertComponent, InsertUsesUpdate, and UpdateComponent unless it invokes the DisplayRowErrors action described in Table A11. It reads the values for properties related to style and appearance, for example CellStyleName and HeaderStyleName.
Select the cell in the Excel worksheet that references the ADF Table component and click the Edit Properties button in the Oracle ADF tab. In the Edit Component: ADF Table dialog, click the browse (...) icon beside the input field for Columns. The Edit Columns dialog appears, listing all the columns of the selected ADF Table component.
4. 5.
Select the column with ID as _ADF_RowKeyColumn. Change the column properties as desired, but do not change the following properties:
6.
If desired, change the position of the column using the Up and Down arrow keys.
7. 8.
Click OK to close Edit Columns dialog. Click OK to close the Edit Component: ADF Table dialog.
Select the cell in the Excel worksheet that references the ADF Table component, and then click the Edit Properties button in the Oracle ADF tab. Add a new column in the ADF Table, and specify the properties as described in Table 79. For more information about adding a column, see Section 7.3.2, "How to Add a Column in an ADF Table Component."
Key Column Properties To ... _ADFDI_TableKeyCellStyle _ADFDI_HeaderStyle False #{_ADFDIres[COMPONENTS_TABLE_ROWKEY_COL_LABEL]} _ADF_RowKeyColumn True OutputText The Value property must be empty.
Table 79
Visible
True
If desired, you may change the position of the Key column using the Up and Down arrow keys.
4.
Click OK.
Note: You must specify the ID property of the new column as _ ADF_RowKeyColumn; otherwise, the column will not be considered to be a Key column, and another Key column will automatically appear at runtime.
7-29
For information about the properties of a TreeNodeList subcomponent, see Section A.6, "TreeNodeList Subcomponent Properties."
The TreeNodeList subcomponent does not support a model-driven list whose control type is input_text_lov or combo_lov. ADF List of Values components using date values are not supported. The TreeNodeList subcomponent may not support model-driven lists for EJB-based data controls in all cases.
Before you begin: It may be helpful to have an understanding of how to create a list of values in ADF Table component. For more information, see Section 7.14, "Creating a List of Values in an ADF Table Component Column." You may also find it helpful to understand functionality that can be added using other ADF Desktop Integration features. For more information, see Section 7.1.2, "Additional Functionality of Table-Type Components."
To create a list of values in an ADF Table component column: 1. Open the integrated Excel workbook.
2. 3.
Select the cell in the Excel worksheet that references the ADF Table component and click the Edit Properties button in the Oracle ADF tab. In the Edit Component: ADF Table dialog, click the browse (...) icon beside the input field for Columns. The Edit Columns dialog appears, listing all the columns of the selected ADF Table component.
4. 5.
Click Add to add a new column. Choose the appropriate option for the newly created column:
Click the browse (...) icon beside the input field for InsertComponent to configure the runtime list of values for insert operations. Click the browse (...) icon beside the input field for UpdateComponent to configure the runtime list of values for update and download operations.
Select TreeNodeList and click OK. Expand the property that you selected in Step 5 and configure values as follows:
Select a tree binding attribute associated with a model-driven list for the List property. Select a value for DependsOnList only if you intend to create a dependent list of values as described in Section 8.8, "Creating Dependent Lists of Values in an Integrated Excel Workbook." The tree binding attribute or list binding you select for DependsOnList serves as the parent list of values in a dependent list of values. Configure the ReadOnly property as desired. For information about these properties, see Section A.6, "TreeNodeList Subcomponent Properties."
Figure 715 shows the property inspector for an ADF Table component column in EditCustomers-DT.xlsx after TreeNodeList is selected as the subcomponent for the column's UpdateComponent property.
7-31
Figure 715 ADF Table Component Column Configured to Display a List of Values
8.
Click OK.
7.14.2 What Happens at Runtime: How the ADF Table Column Renders a List of Values
At runtime, the ADF Table component invokes the Download action and populates each column. This action also populates the list of values in the column that you configure to render a list of values. Figure 716 shows an example from EditCustomers-DT.xlsx of the Summit sample application for ADF Desktop Integration, where Country is the column configured to display a list of values.
Figure 716 Runtime View of an ADF Table Component Column Displaying a List of Values
with the attribute, then the column uses a dropdown list using the TreeNodeList subcomponent.
Note:
If there is no model-driven list associated with the attribute, or if any non-list-based control type is specified, then the column uses an InputText subcomponent. If there is a model-driven list whose control type is input_text_lov or combo_lov, then the column uses an InputText subcomponent.
For more information about creating a model-driven list, see the "How to Create a Model-Driven List" section of the Developing Fusion Web Applications with Oracle Application Development Framework. Support for Dependent List of Values When multiple ModelDrivenColumnComponent list subcomponents are exposed in an ADF Table component, then for each list ADF Desktop Integration determines whether it depends on another model-driven list. It verifies that the bind variable specified for a list references an attribute bound to another list. If the list depends on another model-driven list, the subcomponent's DependsOnList value is set automatically at runtime. As server-side list binding dependencies are determined only for lists in the same tree node, the following tree node list bindings are not supported:
A binding that depends on a list binding in a different tree or tree node A binding that depends on a list binding in the page definition file
ADF Desktop Integration does not support the subcomponent type TreeNodeList in a dynamic column.
Support for Model-Driven List of Values You can also configure a dynamic column to support the List of Values subcomponent where the subcomponent type is determined from model configuration at runtime. At design time, specify the subcomponent type as ModelDrivenColumnComponent for
Working with ADF Desktop Integration Table-Type Components 7-33
the UpdateComponent or InsertComponent properties. At runtime, during dynamic column expansion, the model-driven runtime component is determined before caching the list of values. The remote servlet allows the client to retrieve Model configuration, allowing the client to choose the desired column subcomponent type. For more information about ModelDrivenColumnComponent, see Section 7.15, "Adding a ModelDrivenColumnComponent Subcomponent to Your ADF Table Component."
or:
#{bindings.TreeID.AttributeNamePrefix*.inputValue}
where:
TreeID is the ID of the tree binding used by the ADF Table component TreeNodeID is an optional value that specifies the tree node binding ID. If you omit this value, all matching attributes from the tree binding display regardless of which tree node binding the attribute belongs to. AttributeNamePrefix identifies a subset of attributes that exist within the tree binding's underlying iterator. If you do not specify a value for AttributeNamePrefix, all attributes for the tree binding or tree binding node are returned. Always use the * character.
Note:
While adding a dynamic column, ensure that tree node attribute names are not specified in the page definition file. At runtime, the tree node object returns all attribute names from the underlying iterator. If there are attribute names specified in the page definition file, the tree node object limits the list of available attribute names based on that list.
The following example returns all attributes that begin with the name "period" in the model.EmpView node of the EmpTree binding:
#{bindings.EmpTree.[model.EmpView].period*.inputValue}
7.16.2 What Happens at Runtime: How Data Is Downloaded or Uploaded In a Dynamic Column
When the ADF Table component's Download or DownloadForInsert action is invoked, the ADF Table component automatically updates the dynamic columns so that they contain an up-to-date set of matching attributes. For each invocation of Download, ADF Desktop Integration requires that all rows must have the same set of attributes for the dynamic column. It may generate errors if the set of attributes changes from row to row during Download. If a dynamic column supports both Insert and Update operations, you should specify the same EL expression for the Value properties of the dynamic column's
7-34 Developing Applications with Oracle ADF Desktop Integration
InsertComponent and UpdateComponent subcomponents. At runtime, the ADF Table component expands to include a dynamic column that displays the value of the attribute binding returned by the EL expression. When the ADF Table component's Upload action is invoked, the workbook prompts the end user to determine if the end user wants to continue to upload data when the previously downloaded attributes no longer exist in the tree binding.
Note:
If an Excel AutoFilter is applied on a table with dynamic columns, the AutoFilter is automatically removed every time the dynamic columns are expanded, collapsed, or adjusted.
Support for View Objects with Declarative SQL Mode To support view objects that are configured with declarative SQL mode and customized at runtime, expose a tree binding in the page definition file that has no attributes defined. For example:
<tree IterBinding="DeclSQLModeIterator" id="DeclSQLModeTree"> <nodeDefinition Name="DeclSQLModeTreeNode"/> </tree>
At runtime, the tree binding will return the selected attributes from the underlying declarative SQL mode view object to the integrated Excel worksheet.
or:
#{bindings.TreeID.hints.AttributeNamePrefix*.label}
Specify the same tree binding ID, tree node binding ID, and attribute name prefix values in the HeaderLabel property of the dynamic column as the values you specify for the Value properties of the dynamic column's InsertComponent and UpdateComponent if the dynamic column supports Insert and Update operations.
Note:
The ADF Table component ignores the value of a column's Visible property when you configure a column to be dynamic. For more information about ADF Table component column properties, see Table A10.
If you want the mandatory columns, where the end user must enter a value, to be marked with a character or a string, you must configure the HeaderLabel property. Use the following syntax to write EL expression to add a character or string to all mandatory columns: =IF(#{bindings.TreeID.[TreeNodeID].hints.*.mandatory}, "<prefix_ for_mandatory_cols>", "") & "#{bindings.TreeID.[TreeNodeID].hints.*.label}" For example, the following EL expression adds an asterisk (*) character to the mandatory columns label:
7-35
7.16.4 How to Specify Styles for Dynamic Columns According to Attribute Data Type
You can specify different styles for each data type according to the data type of the column. Use the following syntax to write EL expressions for the CellStyleName property of a dynamic column: =IF("#{bindings.TreeID.[TreeNodeID].hints.*.dataType}"="<data_ type>", <custom_style_expression1>, <custom_style_expression2>) In the following example, the MyDateStyle style is applied to all date columns, and MyDefaultStyle is applied to other data type columns: =IF("#{bindings.MyTree.[myapp.model.MyChildNode].hints.*.dataTyp e}"="date", "MyDateStyle", "MyDefaultStyle") The following example shows another scenario where the MyDateStyle style is applied to all date data type columns, MyNumberStyle is applied to all number data type columns, and MyDefaultStyle is applied to other data type columns: =IF("#{bindings.MyTree.[myapp.model.MyChildNode].hints.*.dataTyp e}"="date", "MyDateStyle", IF("#{bindings.MyTree.[myapp.model.MyChildNode].hints.*.dataType }"="number", "MyNumberStyle", "MyDefaultStyle")) For more information about EL expressions, see Appendix B, "ADF Desktop Integration EL Expressions."
Figure 718 shows the columns that an ADF Read-only Table component which references the Customers tree binding at runtime.
Figure 718 Columns in an ADF Read-only Table Component at Runtime
Notes:
At runtime, inserting a row into the ADF Read-only Table component results in a new Excel row that behaves as if it is part of the downloaded data set, but the new row exists only in Excel. The data from the new row is not uploaded to the server, and does not affect the Fusion web application data. Read-only columns include double-click action sets. However, these actions cannot reliably position on the current row. So, the results of using row-level action sets with the ADF Read-only Table component is not consistent. If you need to use row-level action sets with reliable row positioning, use the ADF Table component instead of the ADF Read-only Table component.
7-37
Before you begin: It may be helpful to have an understanding of ADF Read-only Table component. For more information, see Section 7.17, "Creating an ADF Read-Only Table Component." You may also find it helpful to understand functionality that can be added using other ADF Desktop Integration features. For more information, see Section 7.1.2, "Additional Functionality of Table-Type Components." To insert an ADF Read-only Table component: 1. Open the integrated Excel workbook.
2.
Select the cell in the Excel worksheet where you want to anchor the component. When inserting a table component, you must ensure that the data of two tables does not overlap at runtime, and the selected cell is not a merged cell
3. 4.
In the bindings palette, select the binding to create the ADF Read-only Table component, and then click Insert Binding. In the dialog that appears, select ADF Read-only Table. You can also insert an ADF Read-only Table component by using the components palette or Oracle ADF tab. Select ADF Read-only Table and click Insert Component. If you use the components palette to create the component, you would have to add each column to appear in the component at runtime.
Note:
5. 6.
Configure properties in the property inspector that appears to determine the columns to appear and the actions the component invokes at runtime. Click OK.
Note:
You can modify the properties of the component at a later time by selecting the cell in the worksheet that anchors the component and then displaying the property inspector. To remove the table component, use the Delete ribbon command. For more information, see Section 5.14, "Removing ADF Desktop Integration Components."
7.17.2 How to Manually Add a Column to the ADF Read-only Table Component
You can manually add additional columns to an ADF Read-only Table component or re-add columns that you previously removed. Before you begin: It may be helpful to have an understanding of ADF Read-only Table component. For more information, see Section 7.17, "Creating an ADF Read-Only Table Component." You may also find it helpful to understand functionality that can be added using other ADF Desktop Integration features. For more information, see Section 7.1.2, "Additional Functionality of Table-Type Components." To manually add a column to the ADF Read-only Table component: Open the integrated Excel workbook.
1.
2. 3.
Select the cell in the worksheet that hosts the ADF Read-only Table component and click the Edit Properties button in the Oracle ADF tab. In the Edit Component: ADF Table dialog, click the browse (...) icon beside the input field for Columns. The Edit Columns dialog appears, listing all the columns of the selected ADF Table component
4. 5.
Click Add to add a new column to the ADF Read-only Table component. Set values for the properties of the new column. For information about the properties of an ADF Read-only Table component column, see Table A13.
6.
Click OK.
Select the cell in the Excel worksheet that references the table-type component and click the Edit Properties button in the Oracle ADF tab. For more information, see Section 8.2, "Using Action Sets."
3.
Configure properties for the RowLimit group of properties, as described inTable 710. For more information about these properties, see Section A.1, "Frequently Used Properties in the ADF Desktop Integration."
7-39
Table 710
RowLimit Group of Properties This value... Set to True to limit the number of rows downloaded to the value specified by RowLimit.MaxRows. Specify an EL expression that evaluates to the maximum number of rows to download.
RowLimit.WarningMessa Write an EL expression for this property to generate a message ge for the end user if the number of rows available to download exceeds the number specified by RowLimit.MaxRows. If the value for this property is null, the Download action downloads the number of rows specified by RowLimit.MaxRows displaying the default warning message to the end user. 4.
Click OK.
Figure 719 shows the Edit Component dialog in the EditCustomers-DT.xlsx workbook where the row limit of an ADF Table component is configured.
Figure 719 Limiting Number of Rows of an ADF Table Component
Section 12.7, "Handling Data Conflicts When Uploading Data from a Workbook" Chapter 15, "Using an Integrated Excel Workbook Across Multiple Web Sessions and in Disconnected Mode"
The ADF Table component exposes an action (ClearCachedRowAttributes) that, when invoked, clears the values of cached attributes for the current row of the ADF Table component. Do not configure a component (for example, an ADF Table component's column or an ADF Input Text component) so that an end user can view or edit an attribute binding that you have also specified for an element in the RowData.CachedAttributes array. The RowData.CachedAttributes array caches the values retrieved by the worksheet DownSync action. The worksheet UpSync action sends the values of the RowData.CachedAttributes array to the Fusion web application. This may override edits an end user makes to an attribute binding exposed through a component in the worksheet.
7.19.1 How to Clear the Values of Cached Attributes in an ADF Table Component
Configure a DoubleClickActionSet that includes an action to invoke the ADF Table component's ClearCachedRowAttributes action. Before you begin: It may be helpful to have an understanding of how to clear cached attributes in an ADF Table component. For more information, see Section 7.19, "Clearing the Values of Cached Attributes in an ADF Table Component." You may also find it helpful to understand functionality that can be added using other ADF Desktop Integration features. For more information, see Section 7.1.2, "Additional Functionality of Table-Type Components." To clear the values of cached attributes in an ADF Table component: 1. Open the integrated Excel workbook.
2.
Open the Edit Action dialog for the Oracle ADF component that is going to invoke the DoubleClickActionSet at runtime. For more information about invoking action sets, see Chapter 8.2, "Using Action Sets."
3. 4.
Add an action to the DoubleClickActionSet that invokes the ADF Table component's ClearCachedRowAttributes action. Click OK.
7.19.2 What Happens at Runtime: How the ADF Table Component Clears Cached Values
The action set invokes the ADF Table component's ClearCachedRowAttributes action. This action clears the cached values specified by the
7-41
RowData.CachedAttributes property for the current row of the ADF Table component.
Edit cell values Insert or delete cell values Paste values to cells in the ADF Table component column that they copied elsewhere
A character that resembles an upward pointing arrow appears in a row of the _ADF_ ChangedColumn column if the end user makes a change to data in a corresponding row. Figure 721 shows an example.
Figure 721 Changed Column in an ADF Table Component
This character appears if the end user makes a change to data hosted by a component where the component's ReadOnly property value is False. The ADF Input Text and TreeNodeList subcomponents both have a ReadOnly property. You can write an EL expression or a static string for this ReadOnly property that evaluates to True or False. If you write a static string or an EL expression that evaluates to True, no character appears in the _ADF_ChangedColumn column. For more information about ReadOnly EL expressions and change tracking, see Section 7.21, "Evaluating EL Expression for ReadOnly Properties."
downloading data (Download, DownloadFlaggedRows, DownloadForInsert) uploading data (Upload), and change tracking
7.21.2 What Happens at Runtime: Evaluating EL Expression While Uploading Data or Tracking Changes
During Upload, or when the end user changes values in the editable table, the EL expression is evaluated differently than Download. Specifically, an empty string is substituted for the binding expression prior to evaluation of the EL expression. For example, if you have the following EL expression in an editable cell: =IF("#{row.bindings.color.inputValue}"="RED", True, False) During Upload, or when the end user changes values in the editable table, the EL expression evaluates to =IF(""="RED", True, False), and always returns False.
7.21.3 What You May Need to Know About Evaluating EL Expression While Uploading Data or Tracking Changes
During Upload and change tracking, an extra round trip to the server would be required to retrieve the binding values, in order to evaluate the EL expression properly. The extra round trip to the server would impact performance negatively, and could even require a new login if the end user did not have a currently valid session.
Note:
The same EL expression evaluation behavior also applies to the CellStyleName EL expression property when inserting new worksheet rows during table change tracking.
Due to the difference in behavior, if possible, you should avoid ReadOnly EL Expressions that contain binding expressions. However, if it is important for a given use case to use an attribute value in the ReadOnly expression, you should consider setting the worksheet protection to Automatic. For more information about worksheet protection, see Section 9.7, "Using Worksheet Protection." For example, if you have the following EL expression in a cell: =IF("#{row.bindings.color.inputValue}"="RED", True, False) During Download, the RED cells in this column will be set to Locked and the end user will not be able to edit those cells.
7-43
Using the Explicit Worksheet Setup Action feature of ADF Desktop Integration, you can specify a setup action that is invoked before the client retrieves the binding container metadata.
From the Excel Ribbon, click Workbook Properties. In the Edit Worksheet Properties dialog, expand Data and click the browse icon (...) beside the input field for the SetupActionID property, as shown in Figure 722.
4.
In the Select Binding dialog, select the action that you want to invoke before the binding container metadata is sent to the worksheet, and click OK.
Note: The SetupActionID property accepts ADFm actions only. Validation error is reported if an invalid method is set for the property.
5.
7.22.2 What You May Need to Know About Explicit Worksheet Setup Action
After the action specified in the SetupActionID property runs, the binding container metadata that is sent to worksheet reflects the customization configured in the method. ADF Desktop Integration ensures that the setup action runs only once for any binding container instance. If, for any reason, a new binding container instance becomes associated with the worksheet, the setup action will be invoked again, to ensure it is configured. If any kind of failure occurs during the invoking of the setup action, ADF Desktop Integration is automatically disabled in the worksheet. Logging out, and then logging in, will not enable ADF Desktop Integration in the worksheet. Running Clear All Data command from the Excel Ribbon re-enables ADF Desktop Integration in the worksheet, the setup action runs again on subsequent requests.
7-45
8
8
Section 8.1, "About Adding Interactivity to an Integrated Excel Workbook" Section 8.2, "Using Action Sets" Section 8.3, "Configuring the Runtime Ribbon Tab" Section 8.4, "Displaying Web Pages from a Fusion Web Application" Section 8.5, "Adding a Custom Popup Picker Dialog to an ADF Table Column" Section 8.6, "Creating ADF Databound Search Forms in an Integrated Excel Workbook" Section 8.7, "Creating a Form in an Integrated Excel Workbook" Section 8.8, "Creating Dependent Lists of Values in an Integrated Excel Workbook" Section 8.9, "Using EL Expression to Generate an Excel Formula" Section 8.10, "Using Calculated Cells in an Integrated Excel Workbook" Section 8.11, "Using Macros in an Integrated Excel Workbook"
8-1
Adding interactivity to an integrated Excel workbook permits end users to execute action sets that invoke Oracle ADF functionality in the workbook. It also provides status messages, alert messages, and error handling in the integrated Excel workbook while these action sets execute. In addition to end-user gestures (double-click, click, select) on the ADF Desktop Integration components that invoke action sets, you can configure workbook and worksheet ribbon buttons that end users use at runtime to invoke action sets.
8.1.1 Adding Interactivity to Integrated Excel Workbook Use Cases and Examples
To make your integrated Excel workbook interactive, you can use action sets that are invoked by the end user's gestures. For example, as shown in Figure 82, the Filter Customers ribbon command in EditableCustomerSearch-DT.xlsx uses multiple actions sets to filter data matching the search criteria.
Figure 82 Action Sets of Filter Customers Ribbon Command
Display Web Pages: You can display pages from the Fusion web application with which you integrate your Excel workbook. For more information, see Section 8.4, "Displaying Web Pages from a Fusion Web Application." Dependent List of Values: You can configure an ADF List of Values component as a dependent list of values component whose values are determined by another list of values component. For more information, see Section 8.8, "Creating Dependent Lists of Values in an Integrated Excel Workbook." Styles: You can configure the display of your form-type components using several predefined Excel styles. For more information, see Section 9.2, "Working with Styles." Macros: Use macros and Excel formulas to manage the data that you want to download from or upload to your Fusion web application. For more information, see Section 8.10, "Using Calculated Cells in an Integrated Excel Workbook," and Section 8.11, "Using Macros in an Integrated Excel Workbook."
An action set can be invoked by an end-user's gesture (for example, clicking an ADF Button) or an Excel worksheet event. Where an end-user gesture invokes an action set, the name of the action set property in the ADF component's property inspector is prefaced by the name of the gesture required. The following list describes the property names that ADF Desktop Integration displays in property inspectors, and what user gesture can invoke an action set:
ClickActionSet for an ADF Button component, as the end user clicks the button to invoke the associated action set
8-3
DoubleClickActionSet for an ADF InputText or ADF Output Text component, as the end user double-clicks these components to invoke the associated action set SelectActionSet for a worksheet ribbon button, as the end user selects a button to invoke the associated action set ActionSet for a worksheet event, as no explicit end-user gesture is required to invoke the action set
You invoke the Edit Action dialog from an ADF component, worksheet ribbon button, or worksheet event to define or configure an action set. In addition to defining the actions that an action set invokes, you can configure the action set's Alert properties to provide feedback on the result of invocation of an action set. You configure the Status properties for an action set to display a status message to end users while an action set executes the actions you define. For information about opening the Edit Action dialog, see Section 5.12, "Using the Collection Editors." The Summit sample application for ADF Desktop Integration provides many examples of action sets in use. One example is the ribbon command labeled Upload at runtime in the EditCustomers-DT.xlsx workbook. An action set has been configured for this ribbon command that invokes the ADF Table component's Upload action illustrated by Figure 84 which shows the Edit Action dialog in design mode.
Figure 84 Action Set for Upload Data Button in the EditCustomers-DT.xlsx Workbook
Tip: Write a description in the Annotation field for each action that you add to the Edit Action dialog. The description you write appears in the Members list view and, depending on how you write it, may be more meaningful than the default entry that ADF Desktop Integration generates.
Note:
ADF Desktop Integration invokes the actions in an action set in the order that you specify in the Members list view.
Open the Edit Action dialog and invoke the dropdown list from the Add button illustrated here.
3.
Select ADFmAction and configure its properties as described in the following list:
ActionID Click the browse (...) icon beside the input field for ActionID to invoke the Binding ID picker and select the method action binding that the action set invokes.
Annotation Optionally, enter a comment about the purpose of the action that you are configuring. The value you set for this property has no functional impact.
4.
Click OK.
8-5
Read-only Table components present in a worksheet can be invoked by a SelectActionSet action set.
Figure 85 Choose Component Method Dialog
Note:
An Excel worksheet must include an ADF Table or ADF Read-only Table component before one or more of these components' actions can be invoked by an action set.
Before you begin: It may be helpful to have an understanding of action sets. For more information, see Section 8.2, "Using Action Sets." You may also find it helpful to understand functionality that can be added using other ADF Desktop Integration features. For more information, see Section 8.1.2, "Additional Functionality for Adding Interactivity to an Integrated Excel Workbook." To invoke a component action from an action set: 1. Open the integrated Excel workbook.
2.
Open the Edit Action dialog and invoke the dropdown list from the Add button illustrated here.
3.
Select ComponentAction and configure its properties as described in the following list:
ComponentID Click the browse (...) icon beside the input field for ComponentID to invoke the Choose Component Method dialog and select the component action that the action set invokes at runtime. This populates the ComponentID and Method input fields.
Action The component's action that the action set invokes at runtime.
Annotation Optionally, enter a comment about the purpose of the action that you are configuring. The value you set for this property has no functional impact.
DetailStatusMessage Specify an optional literal value or EL expression that appears in the Status Message window (see Section 8.2.5, "How to Display a Status Message While an Action Set Executes").
4.
Click OK.
8.2.3 What You May Need to Know About an Action Set Invoking a Component Action
Note the following pieces of information about the behavior of action sets in integrated Excel workbooks.
8-7
Startup Shutdown Do not invoke a Dialog action from this event if the Dialog action's Target property is set to TaskPane.
Activate Deactivate
You add an element to the array of events (WorksheetEvent list) referenced by the Events worksheet property. You specify an event and the action set that it invokes in the element that you add. For more information about the Events worksheet property and the worksheet events that can invoke an action set, see Table A19. See Table A14 for more information about action sets. Use the Edit Events dialog to specify an action set to be invoked by a worksheet event. Before you begin: It may be helpful to have an understanding of action sets. For more information, see Section 8.2, "Using Action Sets." You may also find it helpful to understand functionality that can be added using other ADF Desktop Integration features. For more information, see Section 8.1.2, "Additional Functionality for Adding Interactivity to an Integrated Excel Workbook." To invoke an action set from a worksheet event: 1. Open the integrated Excel workbook.
2. 3. 4.
In the Workbook group of the Oracle ADF tab, click Worksheet Properties. In the Edit Worksheet Properties dialog, click the browse (...) icon beside the input field for the Events property. In the Edit Events dialog, click Add to add a new element that specifies an event and a corresponding action set that the event invokes. Figure 87 shows an example from the EditCustomers-DT.xlsx file where the worksheet event, Startup, invokes an action set that invokes the ADF Table component's Download action.
5.
Click OK.
Open the Edit Action dialog of the component. Set values for the properties in the Status group of properties as described in the Table 81.
8-9
Table 81
Status Group of Properties Enter or select this value... True to display a status message. True is the default value. An optional EL expression or literal value that resolves to the status message to display at runtime. For example, the Upload button in the EditCustomers-DT.xlsx file has the following EL expression configured for the Message property: #{res['excel.customers.ribbon.upload.message']}
Title
An optional EL expression or literal value that resolves to the title of the status message to display at runtime. For example, the Upload button in the EditCustomers-DT.xlsx file has the following EL expression configured for the Title property: #{res['excel.customers.ribbon.upload.title']}
Mode
Automatic: ADF Desktop Integration analyzes the action set to determine which progress bars to display. BothBarsAlways: Shows both main and detail progress bars. MainBarOnly: Shows one progress bar only. The bar displays progress through the list of actions. DetailBarOnly: Shows one progress bar only. The bar displays progress of the current action. MainMessageOnly: None of the progress bars are shown.
Figure 88 shows the property values, along with their corresponding visual elements, configured for the Status group of properties of the Upload ribbon command in the EditCustomers-DT.xlsx workbook.
For more information about the Status group of properties, see the entry for Status in Table A14. You can also use the optional DetailStatusMessage property to provide additional information to the user. For more information about the DetailStatusMessage property, see Section 8.2.2, "How to Invoke Component Actions in an Action Set."
4.
Click OK.
8.2.6 What Happens at Runtime: How the Action Set Displays a Status Message
When an action set is invoked, a status message appears if the Status properties are configured to display a status message. Figure 89 shows the status message that appears at runtime when the action set configured for the Upload ribbon command in the EditCustomers-DT.xlsx workbook executes.
At runtime, if the value of the Message property is empty, ADF Desktop Integration provides a default, localized value. If the Title property is empty, the label from the action set container (such as button or ribbon command) is used. If the label of the container is also empty, then the default value provided by ADF Desktop Integration is used.
The progress bar window hides automatically when an action (such as alert, confirm, dialog, or upload options) prompts for user input. Some action types, such as ADFmAction, do not support the display of incremental progress in the detail bar. For example, Figure 810 shows the progress bar of the Commit action with Mode set to BothBarsAlways. Notice that the detail bar appears, but does not show any progress.
In the Automatic mode, if the action set has less than three actions, the status message dialog shows the detail progress bar only. If the action set has three or more actions, the dialog always shows the main bar, but the detail progress bar is shown only if any of the actions in the action set is capable of incremental progress. If none of the actions is capable of incremental progress, the detail bar is suppressed. If required, you can display the detail progress bar without the displaying the main progress bar. Such a configuration may be useful for an action set with a few quick actions and one long action, for example, run a query and then download data. For very quick action sets (for example, DisplayWorksheetErrors), the best practice is to disable the status message.
An alert message does not appear if the end user cancels the execution of an action set. For example, you configure an alert message to appear after an action set that invokes a web page in a popup dialog completes execution. At runtime, the end user cancels execution of the action set by closing the popup dialog using the close button of the Excel web browser control that hosts the popup dialog. In this scenario, no alert message appears. For more information about displaying web pages, see Section 8.4, "Displaying Web Pages from a Fusion Web Application."
You use the Edit Action dialog to configure values for the ActionSet.Alert group of properties. Before you begin: It may be helpful to have an understanding of action sets. For more information, see Section 8.2, "Using Action Sets." You may also find it helpful to understand functionality that can be added using other ADF Desktop Integration features. For more information, see Section 8.1.2, "Additional Functionality for Adding Interactivity to an Integrated Excel Workbook." To add an alert to an action set: 1. Open the integrated Excel workbook.
2. 3.
Open the Edit Action dialog. Set values for the properties in the ActionSet.Alert group of properties as described in Table 82.
ActionSet.Alert Group of Properties Enter or select this value... Select True from the dropdown list to display an alert message once the action set completes. The default value is False. Specify an optional EL expression or literal value that evaluates to a message to appear in the dialog if errors occur during execution of the action set. For example, the Download button in the EditCustomers-DT.xlsx workbook has the following value configured for the FailureMessage property: #{res['excel.customers.ribbon.download.alert.fa ilure']} The Download button invokes an action set that, in turn, invokes the ADF Table component's Download action. The EL expression specified for FailureMessage retrieves error messages if the Download action encounters errors. For more information about error handling, see Section 12.4, "Error Reporting in an Integrated Excel Workbook."
Table 82
OKButtonLabel
Specify an optional EL expression or literal value that evaluates to a message to appear in the OK button of the dialog.
Table 82 (Cont.) ActionSet.Alert Group of Properties For this property... SuccessMessage Enter or select this value... Specify an optional EL expression or literal value that evaluates to a message to appear in the dialog if no errors occur during the execution of the action set. For example, the Download button in the EditCustomers-DT.xlsx workbook has the following value configured for the SuccessMessage property: #{res['excel.customers.ribbon.download.alert.su ccess']}
Figure 811 shows the values configured for a ribbon command's Alert group of properties in the EditCustomers-DT.xlsx workbook. This ribbon command is labeled Download at runtime.
Figure 811 Alert Message Properties in an Action Set
4.
Click OK.
8.2.9 What Happens at Runtime: How the Action Set Provides an Alert
Figure 812 shows the alert message that appears at runtime when the action set invoked by the ADF Button component labeled Download successfully completes execution.
At runtime, if the value of the FailureMessage, OKButtonLabel, or SuccessMessage property is empty, ADF Desktop Integration provides a default, localized value.
An action in the action set fails All actions in the action set complete successfully
For information about how to invoke these editors, or about an ADF component's property inspector, see Chapter 5, "Getting Started with the Development Tools." More information about action set properties can be found in Table A.11. Before you begin: It may be helpful to have an understanding of action sets. For more information, see Section 8.2, "Using Action Sets." You may also find it helpful to understand functionality that can be added using other ADF Desktop Integration features. For more information, see Section 8.1.2, "Additional Functionality for Adding Interactivity to an Integrated Excel Workbook." To configure error handling for an action set: 1. Open the integrated Excel workbook.
2.
Open the appropriate editor or property inspector and configure values for the action set's ActionOptions properties as described in the Table 83.
ActionOptions Properties To... True (default value) so that the action set does not execute any further actions if the current action fails. When set to False, the action set executes all actions regardless of the success or failure of previous actions.
Table 83
Table 83 (Cont.) ActionOptions Properties Set this property... FailureActionID To... Specify an ADF Model action to invoke if an action set does not complete successfully. For example, you can specify an ADF Model action that rolls back changes made during the unsuccessful invocation of the action set. Note that calling an action set that changes a record set's currency during the execution of FailureActionID methods is not supported. The Rollback method also should not be specified as the FailureActionID in an action set. SuccessActionID Specify an ADF Model action to invoke if an action set completes successfully. For example, you can specify an action binding that executes a commit action. A value for this property is optional and you can specify a final action, such as an action binding that executes a commit action, in the action set itself. Note that calling an action set that changes a record set's currency during the execution of SuccessActionID methods is not supported. 3.
Click OK.
Open the Edit Action dialog and click the down arrow in the Add button to open a dropdown list, as illustrated here.
3.
Select Confirmation and configure its Data properties as described in the following list:
CancelButtonLabel
Specify an optional EL expression or literal value that evaluates to a message to appear in the Cancel button of the dialog.
OKButtonLabel Specify an optional EL expression or literal value that evaluates to a message to appear in the OK button of the dialog.
Prompt Specify an optional EL expression or literal value that evaluates to a message to appear as the prompt of the dialog.
Title Specify an optional EL expression or literal value that evaluates to a title of the confirmation dialog to display at runtime.
4.
Optionally, enter a comment in the Annotation property about the purpose of the action that you are configuring. The value you set for this property has no functional impact. Click OK.
5.
Figure 813 shows the Edit Action dialog with default attribute values for the Download ribbon command.
Figure 813 Confirmation Action Attributes
8.2.12 What Happens at Runtime: How the Action Set Provides a Confirmation
Once the action set is invoked, the user is prompted with a confirmation dialog. If the user clicks OK, the next action operation is performed; and if the user clicks Cancel, the Action Set execution terminates without an error.
Note:
If the user cancels a Confirmation action, the FailureActionID binding does not run.
Figure 814 shows a default Confirmation dialog with OK and Cancel buttons.
At runtime, if the value of the CancelButtonLabel, OKButtonLabel, or Prompt property is empty, ADF Desktop Integration provides a default, localized value. If the Title property is empty, the label from the action set container (such as button or ribbon command) is used. If the label of the container is also empty, then the default value provided by ADF Desktop Integration is used.
At runtime, the tab appears as the last tab in the Ribbon and all your configured commands appear in various groups of the tab, as illustrated by Figure 816.
Figure 816 Runtime View of the Ribbon Tab
Figure 817 illustrates the runtime ribbon tab in EditCustomers.xlsx with two commands configured for worksheet. At runtime, the commands are divided into four
8-18 Developing Applications with Oracle ADF Desktop Integration
groups: items that invoke commands on the workbook, items that invoke commands on the current worksheet, a command group to clear all data, and a command workgroup to display ADF Desktop Integration version information.
Figure 817 Runtime View of Ribbon Tab in EditCustomers.xlsx
You configure the Workbook Commands property in the properties of the workbook so that the runtime ribbon tab contains commands that allow the end user to invoke workbook actions. You configure the Ribbon Commands property in the properties of the worksheet so that the ADF Desktop Integration tab contains items allowing a user to invoke an action set. Worksheet command items appear when the worksheet is active. If you remove a workbook command, it does not appear in the runtime tab for that workbook. If you remove all the commands for a given group, the group does not appear when that workbook is active. Figure 818 shows the Worksheet group at runtime where the worksheet actions, that invoke SelectActionSet action sets, appear.
Figure 818 Runtime Worksheet Group
8.3.1 How to Define a Workbook Command Button for the Runtime Ribbon Tab
To define a workbook command button for the runtime ribbon tab, you configure some workbook properties. The following procedure shows how to create or remove an item in the Workbook group by using the workbook action, Login, as an example. Before you begin: It may be helpful to have an understanding of the runtime ribbon tab in Excel. For more information, see Section 8.3, "Configuring the Runtime Ribbon Tab." You may also find it helpful to understand functionality that can be added using other ADF Desktop Integration features. For more information, see Section 8.1.2, "Additional Functionality for Adding Interactivity to an Integrated Excel Workbook." To define a workbook command button: 1. Open the integrated Excel workbook.
2. 3.
In the Workbook group of the Oracle ADF tab, click Workbook Properties. In the Edit Workbook Properties dialog, expand Runtime Ribbon Tab, and select Workbook Commands. Click the browse (...) icon beside the Workbook Commands to display the dialog as illustrated in Figure 819.
4.
Click Add and specify values for the properties of the workbook command buttons as follows: Method Specify the workbook action that you want the workbook command button to invoke. Label Enter a value in the input field that appears as the label at runtime. Alternatively, invoke the expression builder by clicking the browse (...) icon and write an EL expression that resolves to a string value in a resource bundle. Note that the runtime value that appears in the label cannot exceed 1024 characters. A runtime value that exceeds 1024 characters is truncated so that only 1024 characters appear. For more information about using resource bundles, see Section 10.2, "Using Resource Bundles in an Integrated Excel Workbook." For more information about labels, see Section 9.4, "Using Labels in an Integrated Excel Workbook."
5.
Click OK.
Note:
The order of workbook commands in the Edit Workbook Commands dialog is ignored at runtime. The order and grouping of the workbook-level commands is always the same.
8.3.2 How to Configure a Worksheet Command for the Runtime Ribbon Tab
To define a worksheet command, you configure properties for the worksheet using the property inspector. By default, no command buttons are defined for the Worksheet
group in the worksheet properties. You add members to the list that is referenced by the Ribbon Commands property in the properties of the worksheet.
CAUTION: Set the Runtime Ribbon Tab.Visible workbook property to TRUE to display command buttons. If the Runtime Ribbon Tab.Visible is set to FALSE, no command buttons appear. For more information about workbook properties, see Table A18.
Before you begin: It may be helpful to have an understanding of the runtime ribbon tab in Excel. For more information, see Section 8.3, "Configuring the Runtime Ribbon Tab." You may also find it helpful to understand functionality that can be added using other ADF Desktop Integration features. For more information, see Section 8.1.2, "Additional Functionality for Adding Interactivity to an Integrated Excel Workbook." To define a worksheet command button: 1. Open the integrated Excel workbook.
2. 3.
In the Workbook group of the Oracle ADF tab, click Workbook Properties. In the Edit Worksheet Properties dialog, click the browse (...) icon beside the input field for the Ribbon Commands property to invoke the editor, as illustrated in Figure 820. Figure 818 displays how the commands appear at runtime.
4. 5. 6.
Click Add to add a new ribbon button in the Members list of the collection editor. Configure the properties of SelectActionSet to specify the type of action(s) that the ribbon button invokes. Click OK.
Notes:
At runtime, the worksheet commands appear in the same order as they are defined in the Edit Ribbon Commands dialog. The ribbon controls of the toolbar are shared among all open integrated workbooks. If you open two, or more, workbooks using different ribbon buttons occupying the same location in the toolbar, Excel always shows the key tip of the first opened workbook in all open workbooks. This is an Excel limitation.
The value for the Dialog.Target property (Popup or TaskPane) of the component's action set determines where a web page is rendered. The value for the Dialog.Page property specifies the web page to display when the action is invoked. Valid values include a URL relative to the value of the WebAppRoot property or an absolute URL. For example, the EditableCustomerSearch-DT.xlsx workbook specifies the following relative URL as a value for the page to invoke when a user clicks the Filter Customers ribbon command at runtime:
/faces/external/searchForm.jspx
Note:
Example 81 Use of Reserved HTML <span> Element <f:verbatim rendered="#{requestScope.searchAction eq 'search'}"> <span id="ADFdi_CloseWindow">Continue</span> </f:verbatim> <f:verbatim rendered="#{requestScope.searchAction eq 'cancel'}"> <span id="ADFdi_CloseWindow">Abort</span> </f:verbatim>
Figure 821 shows the searchForm.jspx page hosted by the EditableCustomerSearch-DT.xlsx workbook's browser control.
Figure 821 Search Popup Dialog
In scenarios where you cannot use the rendered property of the f:verbatim tag as outlined in Example 81, you may need to:
1. 2.
Create a backing bean that exposes the Dialog action's result value as a property Use an action listener to invoke the backing bean, and an EL expression in the <span> element to set the value ADFdi_CloseWindow to the bean property value.
Whichever approach you take, ADF Desktop Integration monitors the value of ADFdi_CloseWindow to determine when to close the popup dialog. If ADFdi_ CloseWindow references:
An empty string or is not present, the popup dialog remains open. "Continue", the popup dialog closes and the action set invokes its next action. The following example shows ADFdi_CloseWindow assigned a value of "Continue": var closeWindowSpan = document.getElementById("ADFdi_ CloseWindow"); closeWindowSpan.innerHTML = "Continue";
You set the Target property for a Dialog action to Popup to display a web page from the Fusion web application in a modal popup dialog hosted by Excel's web browser control. Displaying a web page in a modal popup dialog differs from displaying a web page in Excel's task pane, because the Dialog action that the action set invokes cannot continue execution until it receives user input. While the popup dialog is open, the end user cannot interact with any other part of the integrated Excel workbook, as the popup dialog retains focus. End users can navigate between multiple web pages from the Fusion web application within the browser control until they close the browser control, or ADF Desktop Integration closes it.
To immediately synchronize the changes that the end user makes to a data control through a popup dialog, specify the next action in the action set after the Dialog action to download all modified bindings to the worksheet (use the DownSync worksheet action) or ADF Table component (use the Download action). This scenario assumes that you specify "Continue" as the value for ADFdi_CloseWindow.
Notes:
If you configure the web page that appears in the popup dialog so that the end user can download an integrated Excel workbook, the Oracle ADF functionality in the integrated Excel workbook is disabled when the end user opens the workbook after download. If you are using the HTML <select> components, such as list box or dropdown list, note that <select> components do not follow z-order configuration when the page is displayed through Dialog actions. In the .NET Web Browser control, on a web page with layered and overlapping components, the <select> components might appear on top of other components. If the Title property is left blank, the web page's title will be used as the dialog's window title.
8.4.2 How to Display a Web Page in ADF Desktop Integration Runtime Task Pane
You can set the Dialog.Target property for an action to TaskPane to display a web page specified by the Dialog.Page property in the ADF Desktop Integration task pane. In contrast to displaying a web page in a popup dialog, displaying a web page in the task pane allows an action set to continue executing actions while the web page displays. End users can access and interact with other parts of the integrated Excel workbook while the web page displays.
Notes:
If the Title property is left blank, the task pane's title will also remain blank. If the Target property of a Dialog action is set to TaskPane, ADF Desktop Integration ignores the value of ADFdi_ CloseWindow (and other elements).
8.4.3 What You May Need to Know About Displaying Pages from a Fusion Web Application
You can keep the data an integrated Excel workbook contains synchronized with a Fusion web application by specifying additional actions in the action set that invokes the Dialog action. You can ensure that the Fusion web application page and the integrated Excel worksheet both use the same data control frame by setting the ShareFrame property of the Dialog action.
Notes:
If your custom web page is based on ADF Faces and opens a popup window, the web page must be configured in a certain way to work properly. On the command component, set the windowEmbedStyle to inlineDocument. For more information, see Developing Web User Interfaces with Oracle ADF Faces. The Dialog.Page property does not accept EL expressions.
8.4.3.1 Keeping an Integrated Excel Workbook and a Fusion Web Application Synchronized
To ensure that data in the integrated Excel workbook and the Fusion web application remains synchronized while end users use pages from the Fusion web application, configure the action set that invokes the Dialog action to:
Send changes from the integrated Excel workbook to the Fusion web application before invoking the Dialog action. Invoke the RowUpSync worksheet action to synchronize changes from the current row in the ADF Table component.
Send changes from the Fusion web application to the integrated Excel workbook after invoking the Dialog action. Invoke the RowDownSync worksheet action to send changes from the Fusion web application to the current row in the ADF Table component.
For DoubleClickActionSet, you must ensure that the server-side model is in the same state after executing the action set as it was before executing the action set. In most cases, it is sufficient to roll back any and all uncommitted changes at the end of each DoubleClickActionSet, as there are no pending uncommitted changes when the action set execution begins. For more information about synchronizing data between an integrated Excel workbook and a Fusion web application, see Chapter 15, "Using an Integrated Excel Workbook Across Multiple Web Sessions and in Disconnected Mode." For information about worksheet actions and ADF Table component actions, see Chapter A, "ADF Desktop Integration Component Properties and Actions."
8.4.3.2 Sharing Data Control Frames Between Integrated Excel Worksheets and Fusion Web Application Pages
Fusion web applications and integrated Excel workbooks both use data control frames to manage the transactions and state of view objects and, by extension, the bindings exposed in a page definition file. When you invoke a Fusion web application's page from an integrated Excel worksheet, you can ensure that the page and the integrated Excel worksheet both use the same data control frame by setting the ShareFrame property of the Dialog action that invokes the page to True. The Page property in the Dialog action specifies the page that the Dialog action invokes. If the Dialog action invokes an absolute URL or a page that is not part of your Fusion web application, ADF Desktop Integration ignores the value of ShareFrame if ShareFrame is set to True. Set ShareFrame to False in the following scenarios:
The Dialog.Page property in the action set references an absolute URL or a page that is not part of your Fusion web application.
The Dialog.Page property in the action set references a page that is part of your Fusion web application, but that does not need to share information with the integrated Excel worksheet. For example, a page that displays online help information.
For more information about data control frames in a Fusion web application, see the "Sharing Data Controls Between Task Flows" section of the Developing Fusion Web Applications with Oracle Application Development Framework.
8.4.3.3 Configuring a Fusion Web Application for ADF Desktop Integration Frame Sharing
When you add the ADF Desktop Integration feature to your Fusion web application, the application is automatically configured to support ADF Desktop Integration frame sharing. Frame sharing allows each worksheet of an integrated Excel workbook to use a dedicated DataControl frame. Web pages displayed in dialogs invoked from each worksheet can then share the same DataControl frame as the integrated Excel worksheet. To verify that your Fusion web application is configured to support frame sharing: 1. Open your Fusion web application project in JDeveloper.
2. 3. 4. 5.
In the Applications window, expand the Application Resources panel. Open the adf-config.xml file available in Descriptors > ADF META-INF node. Click the Source tab to open the source editor. Confirm that the following adf-desktopintegration-servlet-config element is present in the file before the </adf-config> tag:
<adf-desktopintegration-servlet-config xmlns="http://xmlns.oracle.com/adf/desktopintegration/servlet/config"> <controller-state-manager-class> oracle.adf.desktopintegration.controller.impl.ADFcControllerStateManager </controller-state-manager-class> </adf-desktopintegration-servlet-config>
6.
End users to modify values in the Fusion web application's page that you do not want to appear in the ADF Table component of the integrated Excel workbook An ADF Table component's column to be read-only in the integrated Excel workbook Cache data in an ADF Table component over one or more user sessions that is not visible to end users but is modified by a pick dialog For example, an ADF Table component displays a list of product names to end users. A pick dialog is invoked that refreshes the list of product names in the ADF Table component and, as part of the process, sets the value of product IDs. In this scenario, you specify the attribute binding value for the product ID in the ADF Table component's RowData.CachedAttributes property. After the action set executes, the ADF Table component displays the refreshed list of product names in the rows of the Excel worksheet and references the associated product IDs in its RowData.CachedAttributes property.
For information about populating values in the pick dialog, see the "Creating Databound Selection Lists and Shuttles" chapter in the Developing Fusion Web Applications with Oracle Application Development Framework. To invoke a custom pick dialog from an ADF Table component: 1. Open the integrated Excel workbook.
2.
Select the cell in the Excel worksheet that anchors the ADF Table component and click the Edit Properties button in the Oracle ADF tab to display the property inspector. Configure the ADF Table component's RowData.CachedAttributes property to reference attribute binding values. Click the browse (...) icon beside the input field for Columns to display the Edit Columns dialog. In the Members list, select the column from which the end user invokes the pick dialog at runtime. Configure the Actions attribute of DoubleClickActionSet of the column subcomponent (UpdateComponent or InsertComponent), as described in Table 84.
DoubleClickActionSet Properties To... (InsertComponent only) Invoke the CreateInsert action binding if the end user invokes the DoubleClickActionSet from a newly created row in the Excel worksheet's ADF Table component. In this scenario, the ADF Table component's RowUpSync action (invoked in the next action) fails if the Fusion web application does not contain a placeholder row. Invoke the ADF Table component's Table.RowUpSync action to synchronize any pending changes in the current row of the ADF Table component to the Fusion web application. Configure the Dialog action to invoke the pick dialog page from the Fusion web application. Set the Dialog action's ShareFrame property to True. For more information, see Section 8.4, "Displaying Web Pages from a Fusion Web Application."
3. 4. 5. 6.
Table 84
ComponentAction
Dialog
Table 84 (Cont.) DoubleClickActionSet Properties Add this action... ComponentAction To... Invoke the ADF Table component's Table.RowDownSync action to synchronize data from the row in the ADF Table component's iterator in the Fusion web application that corresponds to the current ADF Table component row in the worksheet. (InsertComponent only) If you added a CreateInsert action binding, you should also invoke the Delete action binding to remove the placeholder row.
ADFmAction
7.
Click OK.
2. 3. 4.
ADF Input Text component is used in a simple search form ADF Button component is used in a simple search form ADF Button component is used to invoke an advanced search form
Note:
ADF Desktop Integration does not support usage of the FindMode attribute in page definition files. For more information about the FindMode attribute, see the "pageNamePageDef.xml" section of the Developing Fusion Web Applications with Oracle Application Development Framework.
Take the value the end user enters in the ADF Input Text component. Query for the value. Download the results to an ADF Table or ADF Read-only Table component in the integrated Excel workbook.
Before you begin: It may be helpful to have an understanding of ADF databound search forms. For more information, see Section 8.6, "Creating ADF Databound Search Forms in an Integrated Excel Workbook." You may also find it helpful to understand functionality that can be added using other ADF Desktop Integration features. For more information, see Section 8.1.2, "Additional Functionality for Adding Interactivity to an Integrated Excel Workbook." To create a simple search form in an integrated Excel workbook: Open the integrated Excel workbook. Insert an ADF Input Text component in the Excel worksheet cell where you want the end user to enter the search criteria. Configure the ADF Input Text component so that it assigns the search term, that a user enters, to an attribute binding. Figure 824 shows an example where an ADF Input Text component assigns the user-entered value to the searchTerm attribute binding. The searchTerm, which is a part of variable iterator, is then passed as a NamedData argument to the executeSimpleProductQuery method.
1. 2. 3.
Figure 824 ADF Input Text Component for a Simple Search Form
4. 5.
Optionally, apply a style to the ADF Input Text component to indicate to end users that they can enter a search term in the cell. Optionally, create an ADF Label component in an adjoining cell to indicate to end users that they can enter a search term in the ADF Input Text component you created in Step 2. Create an ADF Button component in the Excel worksheet. Set the Label property of the ADF Button component so that it displays a string at runtime to indicate to end users that they can start a search operation by clicking the button. Open the Edit Action dialog to configure the array of actions (Action list) in the ClickActionSet properties of the ADF Button component. Table 85 describes the actions to invoke in sequence.
ClickActionSet Properties of the ADF Button Component To... Invoke the UpSync worksheet action to copy the value entered in the cell that hosts an ADF Input Text or ADF List of Values component to the Fusion web application. For more information about worksheet actions, see Section A.13, "Worksheet Actions and Properties." Invoke an ADF Model action that is bound to the attribute binding you specified in Step 3. The ADF Model action queries for the end user's search term value referenced by the attribute binding. Invoke the DownSync worksheet action to synchronize any pending changes from the Fusion web application to the ADF Input Text, ADF Output Text, and ADF List of Values components in the worksheet. For more information about worksheet actions, see Section A.13, "Worksheet Actions and Properties." Invoke a Download action from the ADF Table or ADF Read-only Table components to download the results that match the search criteria specified.
6. 7.
8.
Table 85
ADFmAction
Worksheet
Component
9.
Click OK.
Figure 825 shows an example where an ADF Button component invokes the executeSimpleProductQuery action binding using the search term the end user entered in the ADF Input Text component.
Figure 825 ADF Button Component for Simple Search Form
8.6.2 How to Create a Search Form using a Web Page in an Integrated Excel Workbook
You can use the ADF Button component, or the ribbon command, to invoke a page from the Fusion web application that displays a search form to the end user. Configure the action set for the ADF Button component to invoke the Download action for the ADF Table or ADF Read-only Table component so that the search results from the search operation are downloaded to the integrated Excel workbook. For information about creating a search form in a Fusion web application, see the "Creating ADF Databound Search Forms" chapter in the Developing Fusion Web Applications with Oracle Application Development Framework. Before you begin: It may be helpful to have an understanding of ADF databound search forms. For more information, see Section 8.6, "Creating ADF Databound Search Forms in an Integrated Excel Workbook." You may also find it helpful to understand functionality that can be added using other ADF Desktop Integration features. For more information, see Section 8.1.2, "Additional Functionality for Adding Interactivity to an Integrated Excel Workbook." To invoke a web page from an integrated Excel workbook: 1. Open the integrated Excel workbook.
2. 3. 4.
Create an ADF Button component, or a ribbon command, in the Excel worksheet. Set the Label property of the component so that it displays a string at runtime to indicate to end users that they can start a search operation by clicking the button. Use the Edit Action dialog to configure the array of actions (Action list) in the ClickActionSet properties (SelectActionSet properties if you are configuring a ribbon command) of the component. Table 86 describes the actions to invoke in sequence.
Table 86
Actions to Invoke an Advanced Search Form To... Display the page from your Fusion web application that contains the search form. For more information about displaying pages from a Fusion web application, see Section 8.4, "Displaying Web Pages from a Fusion Web Application." Invoke a Download action from the ADF Table or ADF Read-only Table components to download the results that match the search criteria specified.
ComponentAction
5.
Click OK.
Figure 826 shows an example from the EditableCustomerSearch-DT.xlsx workbook where the ribbon command's SelectActionSet contains a Dialog action followed by the ADF Table component's Download action. When the end user invokes the ribbon command, the Dialog action will show the search page (searchForm.jspx) in a browser window. After the end user specifies search criteria in the search page and selects the Search button there, the ADF Table component's Download action is executed. This will retrieve the rows matching the specified search criteria into the integrated worksheet.
Figure 826 Ribbon Command Configured to open a Web Page
ADF Button Use this component to provide end users with a button that can invoke a ClickActionSet. Figure 828 shows an ADF Button labeled Search that invokes a search operation using the search term entered by the end user in the ADF Input Text component.
ADF Input Text Use this component to provide end users with a read/write field where the current value of a binding appears. This component can also be used to input a value, as in the example illustrated in Figure 828, where users enter a search term in the ADF Input Text component.
ADF Output Text Use this component to provide end users with a read-only field where the current value of a binding appears.
ADF List of Values Use this component to provide end users with a dropdown menu from which a user can select a value from a list binding.
ADF Label Use this component to provide end users with instructions or other information on how to use the form you create. For example, the EditWarehouses-DT.xlsx workbook uses ADF Label components to display the title of the form. Figure 828 shows the label with the title text Edit Summit Warehouses.
You use the ADF Desktop Integration task pane to insert the components you require into a worksheet. To create a form in an integrated Excel workbook: 1. Decide which ADF form components you require for the finalized form and insert them in the Excel worksheet. For more information about these components, see Chapter 6, " Working with ADF Desktop Integration Form-Type Components."
2.
Configure the layout and appearance of the components you insert. For more information about configuring the appearance of components, see Chapter 9, "Configuring the Appearance of an Integrated Excel Workbook."
3.
Test your form. For more information about testing an integrated Excel workbook, see Chapter 13, "Testing Your Integrated Excel Workbook."
ADF List of Values You configure properties for this component when you want to create a list of values in the Excel worksheet.
TreeNodeList subcomponent You configure properties for this component when you want to create a list of values in an ADF Table component column.
Using these two components, you can create a dependent list of values in your integrated Excel workbook. A dependent list of values is a list of values component (referred to as a child list of values) whose values are determined by another list of values component (referred to as a parent list of values). The server-side list bindings must be defined such that when the selected item of the parent list of values is changed, the available child list of values items are updated properly. Figure 829 shows an example with two illustrations from the EditWarehouses-DT.xlsx workbook, where the Country field (child list of values) changes when the value in the Region field (parent list of values) changes.
Table 87 describes the dependent list of values implementations you can create using the previously listed components and the requirements to achieve each implementation. Some of the implementations described in Table 87 require model-driven lists. For information about creating a model-driven list, see the "How to Create a Model-Driven List" section of the Developing Fusion Web Applications with Oracle Application Development Framework.
Table 87
Dependent List of Values Configuration Options Requirements Both instances of the ADF List of Values component must reference a list binding. One or both of the list bindings that you reference can be model-driven lists. Both list bindings can reference model-driven lists only if the underlying iterator has at least one row of data. At runtime, if the underlying iterator has zero rows of data and the end user selects a value from the parent list of values (list binding referenced by the ADF List of Values component's DependsOnListID property), the child list of values (list binding referenced by the ADF List of Values component's ListID property) does not get filtered based on the value the end user selects. To work around this scenario, choose one of the following options:
Configuration Render both the parent and child list of values in the Excel worksheet using ADF List of Values components.
Ensure that the underlying iterator has at least one row of data Use an alternative list binding configuration where you expose multiple iterators and all necessary iterators get refreshed
For more information, see Section 8.8.1, "How to Create a Dependent List of Values in an Excel Worksheet." Render both the parent and child list of values in ADF Table component columns using TreeNodeList subcomponents. Both the parent and child list of values (TreeNodeList subcomponents) must reference tree binding attributes associated with model-driven lists. For more information, see Section 8.8.3, "How to Create a Dependent List of Values in an ADF Table Component's Columns." The child list of values (TreeNodeList subcomponent) must reference a tree binding attribute associated with a model-driven list. The parent list of values (ADF List of Values component) must reference a list binding. For more information, see Section 8.8.5, "Creating a Dependent List of Values in an Excel Worksheet and an ADF Table Component Column."
Render the parent list of values in an ADF List of Values component and the child list of values in an ADF Table component column using the TreeNodeList subcomponent.
Note the following points if you plan to create a dependent list of values:
When the cell value referenced by DependsOnList or DependsOnListID is changed, ADF Desktop Integration overrides any previous changes to the child component list of values without warning the end user. The dependent list of values does not work unless the list specified in the DependsOnList (or DependsOnListID) property is referenced by a component in the Excel worksheet. If a circular dependency is defined (List A depends on List B, and List B depends on List A), the first dependency (List A depends on List B) triggers the expected behavior. ADF Desktop Integration considers other dependencies to be misconfigurations. You can create a chain of dependencies as follows: List A depends on List B List B depends on List C
In this scenario, a change in List C (grandparent list of values) updates both Lists A (grandchild list of values) and B (child list of values). If you create a similar scenario, you must ensure that both the grandchild list of values and the child list of values, get refreshed whenever the parent list of values selection is changed. You can do this by specifying the two bind variables on the grandchild list of values to set up an implicit dependency between the view attributes. Another way
8-36 Developing Applications with Oracle ADF Desktop Integration
is to declare explicit attribute dependencies between each of the view attributes that have model-driven lists configured. For example, specify that attribute A depends on attribute B and attribute C, and attribute B depends on attribute C.
Caching in a dependent list of values is discussed in Section 15.4, "Caching Lists of Values for Use in Disconnected Mode." ADF Desktop Integration caches the values that appear in a dependent list of values. Hence, the dependent list item values for a given parent list selection must remain constant across all rows of an ADF Table component. ADF List of Values components using date values are not supported.
Open the integrated Excel workbook. Insert two ADF List of Values components into your integrated Excel workbook, as described in Section 6.6, "Inserting an ADF List of Values Component." In the property inspector for the ADF List of Values component that is to serve as the parent in the dependent list of values, set the value of the ListOfValues.ListID property to the list binding that is the parent. In the property inspector for the ADF List of Values component that is to serve as the child in the dependent list of values, set the following properties:
5.
ListOfValues.ListID Specify the list binding that is the child in the dependent list of values.
ListOfValues.DependsOnListID Select the list binding that you specified for the ADF List of Values component that serves as a parent in Step 4.
Figure 830 shows the property inspector for the child ADF List of Values where the RegionId list binding is specified as the parent list of values and CountryId list is the dependent list of values.
Figure 830 Design Time Dependent List of Values in an Excel Worksheet
6.
Click OK.
8.8.2 What Happens at Runtime: How the Excel Worksheet Renders a Dependent List of Values
At runtime, ADF Desktop Integration renders both instances of the ADF List of Values component. When the end user selects a value from the parent list of values, the selected value determines the list of values in the child list. Figure 831 shows an example where Country, a dependent list value, displays only the states from the selected Region list value.
Figure 831 Runtime Dependent List of Values in an Excel Worksheet
8.8.3 How to Create a Dependent List of Values in an ADF Table Component's Columns
Use instances of the TreeNodeList subcomponent to render both lists of values in a dependent list of values in ADF Table component columns at runtime. Specify a tree binding attribute as a value for the parent TreeNodeList subcomponent's List property. You also specify a tree binding attribute as a value for the child TreeNodeList subcomponent's List property and the same tree binding attribute referenced by the parent TreeNodeList subcomponent as a value for its DependsOnList property. Ensure that both tree binding attributes are associated with model-driven lists before you add the tree binding to your page definition file. For information about creating a model-driven list, see the "How to Create a Model-Driven List" section of the Developing Fusion Web Applications with Oracle Application Development Framework. For information about adding a tree binding to your page definition file, see Section 4.3, "Working with Page Definition Files for an Integrated Excel Workbook." For information about the TreeNodeList subcomponent, see Section A.6, "TreeNodeList Subcomponent Properties." Before you begin: It may be helpful to have an understanding of dependent list of values. For more information, see Section 8.8, "Creating Dependent Lists of Values in an Integrated Excel Workbook." You may also find it helpful to understand functionality that can be added using other ADF Desktop Integration features. For more information, see Section 8.1.2, "Additional Functionality for Adding Interactivity to an Integrated Excel Workbook." To create a dependent list of values in an ADF Table component: Open the integrated Excel workbook. If not present, insert an ADF Table component. For more information, see Section 7.3, "Inserting ADF Table Component into Excel Worksheet."
3. 4.
1. 2.
In the property inspector for the ADF Table component, invoke the Edit Columns dialog by clicking the browse (...) icon beside the input field for Columns. Add a new column (or modify an existing column) to serve as the parent list of values. Specify TreeNodeList as the column's subcomponent type. For more information about creating a list of values, see Section 7.14, "Creating a List of Values in an ADF Table Component Column." Add a new column (or modify an existing column) to serve as the child list of values. Specify TreeNodeList as the column's subcomponent type. For more information about creating a list of values, see Section 7.14, "Creating a List of Values in an ADF Table Component Column." Specify the tree binding attribute of the parent list of values as a value for the DependsOnList property in the child list of values column. Figure 832 shows the property inspector for a dependent TreeNodeList subcomponent, where the RegionId tree binding attribute is specified for the parent list of values and the CountryId tree binding attribute is specified for the child list of values.
5.
6.
Figure 832 Design Time Dependent List of Values in an ADF Table Component's Column
7.
Click OK.
8.8.4 What Happens at Runtime: How the ADF Table Component Column Renders a Dependent List of Values
At runtime, the ADF Table component renders both instances of the TreeNodeList subcomponent in the columns that you configured to display these instances. When the end user selects a value from the parent list of values, the selected value determines the list of values in the child list. Figure 833 shows an example where the value that the end user selects in the Region column list of values results in the corresponding values for sub-category appearing in the Country column list of values.
Figure 833 Runtime Dependent List of Values in an ADF Table Component's Columns
Note:
If the child list and the parent list are bound to columns in the same ADF Table component, the child list items are changed for the current row only, when the end user changes the parent list selection.
8.8.5 Creating a Dependent List of Values in an Excel Worksheet and an ADF Table Component Column
Use an instance of the ADF List of Values component and an instance of the TreeNodeList subcomponent to create a dependent list of values where you render the parent and the child list of values.
Parent list of values in the Excel worksheet An instance of the ADF List of Values component renders the parent list of values in the Excel worksheet.
Child list of values in an ADF Table component column An instance of the TreeNodeList subcomponent renders the child list of values in the ADF Table component column.
Specify a list binding as a value for the parent ADF List of Values component's ListID property. You specify a tree binding attribute as a value for the child TreeNodeList subcomponent's List property, and the same list binding referenced by the parent ADF List of Values component as a value for its DependsOnList property. Ensure that the tree binding attribute is associated with a model-driven list before you add the tree binding to your page definition file. For information about creating a model-driven list, see the "How to Create a Model-Driven List" section of the Developing Fusion Web Applications with Oracle Application Development Framework. For information about adding a list and tree binding to your page definition file, see Section 4.3, "Working with Page Definition Files for an Integrated Excel Workbook." For more information about the ADF List of Values component, see Section A.5, "ADF List of Values Component Properties." For information about the TreeNodeList subcomponent, see Section A.6, "TreeNodeList Subcomponent Properties." Before you begin: It may be helpful to have an understanding of dependent list of values. For more information, see Section 8.8, "Creating Dependent Lists of Values in an Integrated Excel Workbook." You may also find it helpful to understand functionality that can be added using other ADF Desktop Integration features. For more information, see Section 8.1.2, "Additional Functionality for Adding Interactivity to an Integrated Excel Workbook." To create a dependent list of values in an Excel worksheet and an ADF Table component column: 1. Open the integrated Excel workbook.
2. 3.
Insert an ADF List of Values component into your integrated Excel workbook, as described in Section 6.6, "Inserting an ADF List of Values Component." In the property inspector for the ADF List of Values component, set the value of the ListID property to the list binding that is to serve as the parent list of values in the dependent list of values. Click OK. Open the property inspector for the ADF Table component and invoke the Edit Columns dialog by clicking the browse (...) icon beside the input field for Columns. Click Add to add a new column to the ADF Table component to serve as the child list of values in the runtime-dependent list of values.
4. 5.
6.
7.
Click the browse (...) icon beside the input field for InsertComponent to configure the runtime list of values for insert operations. Click the browse (...) icon beside the input field for UpdateComponent to configure the runtime list of values for update and download operations.
Select TreeNodeList and click OK. Expand the property that you selected in Step 7 and configure values as follows:
Select the same list binding that you specified as a value for the ADF List of Values component's ListID property in Step 3 as a value for the DependsOnList property. Select a tree binding attribute associated with a model-driven list for the List property. Configure the ReadOnly property as desired.
Figure 834 shows the ADF Table property inspector for a child ADF Desktop Integration Tree Node component of WarehouseLocations-DT.xlsx where the RegionList list binding is specified as the parent list of values.
Figure 834 Design Time Dependent List of Values in an Excel Worksheet and an ADF Table Component's Column
8.8.6 What Happens at Runtime: How the Excel Worksheet and the ADF Table Component Column Render a Dependent List of Values
At runtime, the ADF List of Values component renders the parent list of values and the ADF Table component renders the child list of values in the column that you configured to display the TreeNodeList subcomponent. When the end user selects a value from the parent list of values, the selected value determines the list of values in the child list. Figure 835 shows an example from WarehouseLocations-DT.xlsx where the value that the end user selects in the Region list of values determines the list of values that appears in the Country column of the ADF Table component.
Figure 835 Runtime-Dependent List of Values in an Excel Worksheet and an ADF Table Component's Column
Note:
When the parent list is bound to a cell in the worksheet and the child list is bound to an ADF Table Component column, the child list items are updated for all rows in the table when the end user changes the parent list selection.
If you write an EL expression using the HYPERLINK function, you should select the Locked checkbox in the Protection tab of the Format Cells dialog for the custom style that you apply to prevent error messages appearing.
Note:
When using EL expressions in formulas, ensure that after the EL expression is evaluated, the resulting Excel formula has no more than 255 characters. This applies to formulas used to set conditional values to component properties in the editor.
Insert an ADF Output Text component into the Excel worksheet. Write an EL expression for the Value property of the ADF Output Text component. The EL expression that you write invokes the Excel HYPERLINK function and uses the Excel T function to evaluate the output. In Example 82, you entered the following EL expression for the Value property:
=T("=HYPERLINK(""http://www.oracle.com/technetwork/developer-tools/adf/overview /index-085534.html"", ""#{res['excel.workbook.powerby']}"")")
Note:
Excel requires that you write double double quotes (for example, ""#{res['excel.workbook.powerby']}"") in the EL expression so that it can evaluate the expression correctly.
4.
Click OK.
8.9.2 What Happens at Runtime: How a Cell Displays a Hyperlink using an EL Expression
ADF Desktop Integration evaluates the EL expression that you write at runtime. In the following example, ADF Desktop Integration:
Retrieves the value of the excel.workbook.powerby from the resource file Inserts the result into a hyerlinked cell that a user can click
Figure 836 shows the runtime view of the example configured in Section 8.9.1, "How to Configure a Cell to Display a Hyperlink Using EL Expression." When the end user clicks the cell that hosts the ADF Output Text component, the Oracle ADF Desktop Integration home page opens in the web browser.
Formulas can be entered in cells that reference Oracle ADF bindings and cells that do not reference Oracle ADF bindings End users of an integrated Excel workbook can enter formulas at runtime You (developer of the integrated Excel workbook) can enter formulas at design time During invocation, the ADF Table component actions Upload and RowUpSync send the results of a formula calculation to the Fusion web application and not the formula itself Excel recalculates formulas in cells that reference Oracle ADF bindings when these cells are modified by: Invocation of the ADF Table component RowDownSync and Download actions Rendering of Oracle ADF components
The ADF Table and ADF Read-only Table components insert or remove rows as they expand or contract to accommodate data downloaded from the Fusion web application. Formulas are replicated according to Excel's own rules. You can enter formulas above or below a cell that references an ADF Table or ADF Read-only Table component. A formula that you enter below one of these components maintains its position relative to the component as the component expands or contracts to accommodate the number of rows displayed.
For more information about Excel functions, see the Function reference section in Excel's online help documentation.
Write the Excel formula that performs a calculation on a range of cells at runtime. For example: =SUM(OFFSET(G14,1,0):OFFSET(G15,-1,0)) where SUM calculates the total of values in the range of cells currently referenced by G14 and G15. Figure 837 shows the design time view of the Excel formula in the integrated Excel workbook.
Figure 837 Design Time View of Excel Formula in an Integrated Excel Workbook
3.
Save your changes and switch to runtime mode to test that the Excel formula you entered evaluates correctly.
8.10.2 What Happens at Runtime: How Excel Calculates the Sum of a Table-Type Component Column
Figure 838 shows the runtime view in the integrated Excel workbook when the Excel formula shown in Figure 837 is evaluated. The Excel formula calculates the total of the values in the range of cells that you specified in design mode.
Macros triggered by an Excel event do not get triggered if the Excel event is invoked by ADF Desktop Integration. ADF Desktop Integration code invoked by an Excel event is executed when the Excel event is triggered by a macro.
9
9
Section 9.1, "About Configuring the Appearance of an Integrated Excel Workbook" Section 9.2, "Working with Styles" Section 9.3, "Applying Styles Dynamically Using EL Expressions" Section 9.4, "Using Labels in an Integrated Excel Workbook" Section 9.5, "Using Styles to Improve the User Experience" Section 9.6, "Branding Your Integrated Excel Workbook" Section 9.7, "Using Worksheet Protection"
9-1
9.1.2 Additional Functionality for Configuring the Appearance of an Integrated Excel Workbook
After you have applied styles to configure the appearance of your integrated Excel workbook, you may find that you need to add additional functionality to configure your workbook. Following are links to other functionalities that you can use:
Branding: In addition to styles, ADF Desktop Integration provides a collection of properties (BrandingItems) that enable you to brand your integrated Excel workbook with application name, application version details, and copyright information. For more information, see Section 9.6, "Branding Your Integrated Excel Workbook." Localization: You can customize the integrated Excel workbook as part of the process to internationalize and localize with the Fusion web application. For more information, see Chapter 10, "Internationalizing Your Integrated Excel Workbook."
_ADFDI_FormBottomStyle
_ADFDI_FormDoubleClickCellStyle _ADFDI_FormTopStyle _ADFDI_HeaderStyle _ADFDI_InputTextStyle _ADFDI_LabelStyle _ADFDI_OutputTextStyle _ADFDI_ReadOnlyTableStyle _ADFDI_TableCellROStyle _ADFDI_TableCellStyle _ADFDI_TableChangedColumnStyle _ADFDI_TableDoubleClickCellStyle _ADFDI_TableFlagColumnStyle _ADFDI_TableKeyCellStyle _ADFDI_TriangleHeaderStyle
You can merge these styles and other styles that you define yourself from an integrated Excel workbook into another Excel workbook that you intend to integrate with a Fusion web application. You may create additional styles for use in your Excel workbook. For example, to add a date-specific formatting, you can duplicate _ADFDI_ TableCellStyle, call it MyTableCellDateStyle, and add your date-specific formatting. Once you have decided what styles to apply to the ADF Desktop Integration components at runtime, you can write EL expressions to associate a style with a component. The ADF Desktop Integration component properties that include StyleName in their name take an EL expression as a value. The ADF Label component and the Label property of other ADF components also support EL expressions. These EL expressions can retrieve the values of string keys defined in resource bundles or the values of attribute control hints defined in your Fusion web application. For more information about creating new styles and merging styles into a workbook, see Excel's documentation.
9.2.2 Excel's Date Formats and Microsoft Windows' Regional and Language Options
Some formats in the Date category of the Number styles that Excel can apply to cells change if a user changes the locale of the local system using the Regional and Language Options dialog that is accessible from the Microsoft Windows Control Panel. The * character precedes these formats in the Type list. Figure 92 shows an example of a Date type that formats dates in a cell using French (France) conventions.
9-3
If the end user changes the regional options of a system to use English (United States), as illustrated in Figure 93, the cells that are formatted with the style in Figure 92 use the English (United States) conventions.
Figure 93 US English Date Formats in Excel
Note:
In order for Excel to properly format and manipulate date values with no time component, the form or table attributes must use the java.sql.Date data type in the application's model definition.
You may also find it helpful to understand functionality that can be added using other ADF Desktop Integration features. For more information, see Section 9.1.2, "Additional Functionality for Configuring the Appearance of an Integrated Excel Workbook." To apply a style: 1. In the integrated Excel workbook, select the cell that references the Oracle ADF component you want to modify and then click the Edit Properties button in the Oracle ADF tab.
2. 3.
Select the StyleName property and click the browse (...) icon to display the Edit Expression dialog. Expand the Styles node and select the style to apply to cell at runtime. For example, apply a heading style (Heading 4 style) to the Binding Warehouse ID output text field. Applying the Heading 4 style rather than a general style to the field results in data appearing as bold and in blue color.
4.
Click Insert Into Expression to insert the selected style into the Expression field. Figure 94 shows the Edit Expression dialog.
5.
Click OK.
9-5
If a cell that references an ADF component has a style applied to it that differs from the style defined in the properties of the ADF component, the ADF component overwrites the existing style at runtime and applies the style defined by its properties. For example, Figure 95 shows the runtime values of Binding Warehouse ID after the Heading 4 style is applied, overriding the default _ADFDI_OutputTextStyle style.
Figure 95 Runtime Values After Applying Another Style
Example 92 uses a mixture of Excel formulas and ADF binding expressions to handle errors and type conversion.
Example 92 EL Expressions to Handle Errors and Type Conversion =IF(ISERROR(VALUE("#{bindings.DealSize}")), "BlackStyle", IF(VALUE("#{bindings.DealSize}") > 300, "RedStyle", "BlackStyle"))
It then replaces the EL expression with the runtime value, as in the following example, where the expression evaluated to Closed:
=IF("Closed" = "Closed", "MyReadOnlyStyle", "MyReadWriteStyle")
Excel evaluates the formula and, in this example, applies the MyReadOnlyStyle style.
Before you begin: It may be helpful to have an understanding of how to apply styles dynamically. For more information, see Section 9.3, "Applying Styles Dynamically Using EL Expressions." You may also find it helpful to understand functionality that can be added using other ADF Desktop Integration features. For more information, see Section 9.1.2, "Additional Functionality for Configuring the Appearance of an Integrated Excel Workbook." To write an EL expression that applies a style at runtime: 1. Open the integrated Excel workbook.
2. 3. 4.
Select a cell in the Excel worksheet that references the Oracle ADF component for which you want to write an EL expression. Click the Edit Properties button in the Oracle ADF tab to display the property inspector. Select the property in the property inspector with which you want to associate an EL expression and click the browse (...) icon to display the Edit Expression dialog.
9-7
Note:
The Edit Expression dialog appears only if the Oracle ADF component that you selected in Step 2 supports EL expressions. Depending on the context, the browse (...) icon can launch other editors such as the Edit Action dialog.
The Edit Expression dialog, as illustrated in Figure 96, displays a hierarchical list of the Oracle ADF components, bindings, styles, resources, and Excel functions that you can reference in EL expressions. For more information about the syntax of EL expressions that you enter in this dialog, see Appendix B, "ADF Desktop Integration EL Expressions."
9.3.3 What You May Need to Know About EL Expressions That Apply Styles
EL expressions that evaluate to styles are applied when:
An ADF Table component invokes its Download or DownloadForInsert actions Rows are inserted into an ADF Table component A worksheet invokes its DownSync action
An ADF Table component invokes its RowDownSync action The end user edits the format properties of a cell Note also that an EL expression that evaluates to a style is not reevaluated when the end user edits a cell's value.
The runtime value of an EL expression does not match a style defined in the end user's integrated Excel workbook In this scenario the style formats of the targeted cells do not change. Instead, they retain their existing style formats. If you configured client-side logging, ADF Desktop Integration generates an entry in the log file when an EL expression evaluates to a style that is not defined in the end user's integrated Excel workbook. For more information about client-side logging, see Section C.3, "Generating Log Files for an Integrated Excel Workbook."
Figure 97 Design Time View of an ADF Label Component and an ADF Input Text Component with Label Property
At runtime, these EL expressions resolve to string keys defined in the res resource bundle that is registered with the Summit sample application for ADF Desktop Integration. You define resource bundles in the workbook properties dialog. For information about referencing string keys from a resource bundle, see Section 10.2, "Using Resource Bundles in an Integrated Excel Workbook." Figure 98 shows the corresponding runtime view of the ADF Label component and ADF Input Text component illustrated in design mode in Figure 97.
Figure 98 Runtime View of an ADF Label Component and an ADF Button Component with Label Property
9-9
Figure 99 EL Expression That Retrieves the Value of an Attribute Control Hint for a Label Property
Attribute control hints can be configured for both view objects and entity objects. Information about how to add an attribute control hint to an entity object can be found in the "Defining Attribute Control Hints for Entity Objects" section of the Developing Fusion Web Applications with Oracle Application Development Framework. Information about how to define a UI hint for a view object can be found in the "Defining UI Hints for View Objects" section of the Developing Fusion Web Applications with Oracle Application Development Framework.
Providing end users with instructions on how to use Oracle ADF components such as ADF Button and ADF Input Text components.
The ADF Label component and the Label property of other ADF components is useful for this task, as you can write labels that instruct the end user on how to use the component.
For information about using resource bundles, see Section 10.2, "Using Resource Bundles in an Integrated Excel Workbook."
9.5.2 What You May Need to Know About the Read-Only Property in an Integrated Excel Workbook
Note the following points about the read-only property in an integrated Excel workbook:
ADF Output Text, ADF Label, and ADF Table header row do not have read-only properties. However, these components have implied read-only behavior. In addition, end users can enter values in the cells that host these components and temporarily change the values that appear in these cells. ADF Desktop Integration ignores these changes when uploading from the worksheet and overwrites them when it downloads data from the Fusion web application. The ADF Input Text component, ADF List of Values component, and TreeNodeList subcomponent each have a read-only property (ReadOnly).
Note:
If you specify an Excel formula in the Value property of an ADF Input Text component, the component behaves as if its ReadOnly property were True. The component ignores the actual value of the ReadOnly property.
To protect the values of read-only cells at runtime, set the worksheet protection to automatic. When an attempt is made to edit a read-only cell after enabling worksheet protection, Excel displays a warning message and the edit is blocked. For more information about worksheet protection, see Section 9.7, "Using Worksheet Protection." Do not use the Excel's Protect Sheet or Protect Workbook features directly in an integrated Excel workbook. Also, ensure that end users do not use these features.
To prevent end-user confusion, apply styles to components, such as the ADF Output Text component, that indicate to end users whether a component is read-only or can be edited. By default, the ADF Output Text component uses the predefined style, _ ADFDI_OutputTextStyle. You can define your own styles and apply them to components as described in this chapter. For more information about the properties that ADF Desktop Integration components support, see Appendix A, "ADF Desktop Integration Component Properties and Actions."
In the Workbook group of the Oracle ADF tab, click Workbook Properties. In the Edit Workbook Properties dialog, click the browse (...) icon beside the input field for BrandingItems. In the Edit BrandingItems dialog, click Add and specify values for the new element as follows:
Name Specify the name, or the EL expression, of the branding item to define.
Value Specify a literal string or click the browse (...) icon to invoke the expression builder and write an EL expression that retrieves a value at runtime.
BrandingItems must use literal strings or resource expressions, and must not contain any binding expression. Figure 911 shows the design time view of branding items in the Summit sample application for ADF Desktop Integration.
Figure 911 Design Time View of Branding Items in the Summit Sample Application for ADF Desktop Integration
5.
Click OK.
Figure 912 Runtime View of Branding Items in the Summit Sample Application for ADF Desktop Integration
In the Workbook group of the Oracle ADF tab, click Workbook Properties. In the Edit Worksheet Properties dialog, expand the Protection property and configure values as follows:
To enable worksheet protection at runtime, set the Mode to Automatic. If desired, provide a value in the Password field. The end user cannot turn off sheet protection at runtime without knowing this value. Note that the password is not encrypted and that the maximum password length allowed by Excel is 255 characters. If you specify a longer password, it will be truncated silently at runtime when sheet protection is toggled.
Figure 913 shows the design time view of worksheet protection in the Summit sample application for ADF Desktop Integration.
Figure 913 Design Time View of Worksheet Protection in the Summit Sample Application for ADF Desktop Integration
4.
Click OK.
When worksheet protection is enabled, ADF Desktop Integration controls the Locked property for cells that are within the bounds of ADF Desktop Integration components. The Locked property of cells outside the bounds of ADF Desktop Integration components is not affected. At runtime, ADF Desktop Integration evaluates the read-only behavior of its components. Some components such as ADF Label and ADF Output Text, are always read-only, and other components, such as ADF Input Text, have a read-only property. At runtime, the Locked property is set to true when read-only for the component evaluates to true. The header labels of ADF Table components are always read-only, but column subcomponents might be ADF Output Text or ADF Input Text. At runtime, each components read-only behavior is evaluated and the corresponding cell's Locked property is set to the appropriate value.
The ADF Table components cannot be sorted, as they include read-only cells in the Key column. The end user can insert a full row or column. However, once inserted, they cannot be deleted. The end user cannot insert partial rows or columns.
10
10
Section 10.1, "About Internationalizing Your Integrated Excel Workbook" Section 10.2, "Using Resource Bundles in an Integrated Excel Workbook" Section 10.3, "Localization in ADF Desktop Integration"
Internationalized Data ADF Desktop Integration supports both single- and double-byte character sets. It marshals data transmitted between an Excel worksheet and a Fusion web application into XML payloads. These XML payloads use UTF-8 encoding with dates, times, and numbers in canonical formats.
Locale The locale of the system where the Excel workbook is used determines the format for dates, times, and numbers. These settings (formats and the locale of the system) may differ from the settings used by the Fusion web application. ADF Desktop Integration does not attempt to synchronize these settings, but it ensures that the data retains its integrity. ADF Desktop Integration does not provide a mechanism for end users to change the language or display settings of the Oracle ADF components in an integrated Excel workbook at runtime. When configuring or applying styles to ADF components in an integrated Excel workbook, configure or choose styles that are locale-sensitive. For more information, see Section 9.2, "Working with Styles."
For more information about internationalizing Fusion web applications, see the "Internationalizing and Localizing Pages" chapter in the Developing Web User Interfaces with Oracle ADF Faces.
Security: Whether you are using a secure Fusion web application or not, you must be aware of security implementations in your integrated Excel workbook. For more information, see Chapter 11, "Securing Your Integrated Excel Workbook." Validating integrated Excel workbook: You can configure server-side and client-side validation for the Fusion web application and the integrated Excel workbook. For more information, see Chapter 12, "Adding Validation to an Integrated Excel Workbook." Publishing and deploying integrated Excel workbook: The final step after you design and validate your integrated Excel workbook is to publish and deploy it. For more information, see Chapter 14, "Deploying Your Integrated Excel Workbook."
2. 3.
In the Workbook group of the Oracle ADF tab, click Workbook Properties. In the Edit Workbook Properties dialog, click the browse (...) icon beside the input field for Resources to display the Edit Resources dialog shown in Figure 102.
4.
Specify values for the resource bundle and then click OK. For information about the values to specify for a resource bundle, see the entry for Resources in Table A18.
Tip: While registering a resource bundle class, do not include the file extension.
You may also find it helpful to understand functionality that can be added using other ADF Desktop Integration features. For more information, see Section 10.1.2, "Additional Functionality for Internationalizing Integrated Excel Workbook." To override resources that are not configurable: 1. Create a resource bundle in your Fusion web application. For information about creating a resource bundle, see the "Manually Defining Resource Bundles and Locales" section in the Developing Web User Interfaces with Oracle ADF Faces.
2.
Define the string key values you want to appear at runtime in the resource bundle for the string keys listed in Appendix E, "String Keys in the Overridable Resources." Set _ADFDIres as the value of the Alias property when you register the resource bundle you created in Step 1. For information about how to register a resource bundle, see Section 10.2.1, "How to Register a Resource Bundle in an Integrated Excel Workbook."
3.
Table E1 describes the string keys in the overridable resources that ADF Desktop Integration supports. Supply an alternative value to the value listed in the English value column for each string key in the overridable resource. Note that override resources should not be used in component properties, they are only intended for the original usages.
10.2.3 What Happens at Runtime: Override Resources That Are Not Configurable
ADF Desktop Integration retrieves the values of string keys listed in Table E1 that you defined in the resource bundle you created. It retrieves the values of other string keys that you did not define in the resource bundle you created from the reserved resource bundle.
Properties bundle (.properties) List resource bundle (.rts) Xliff resource bundle (.xlf)
For more information about resource bundles, see the "Manually Defining Resource Bundles and Locales" section in the Developing Web User Interfaces with Oracle ADF Faces.
user closes and reopens the workbook so that it retrieves the modified value from the Fusion web application. For more information about the ClearAllData workbook action, see Table A17.
Area subject to localization Microsoft operating system Microsoft Office Web pages displayed in ADF Desktop Integration Dialog actions ADF Desktop Integration client resources ADF Desktop Integration server resources ADF Desktop Integration custom resource bundles
Figure 103 illustrates how various elements involved in a Fusion web application play their role in translation.
For more information about localization in ADF Desktop Integration, see the "Oracle ADF Desktop Integration Localization whitepaper" on OTN at: http://www.oracle.com/technetwork/developer-tools/adf/overview/i ndex-085534.html
public class CustomUserPrefsHandler { public Locale getLocale () { UserPref info = (UserPref) ADFContext.getCurrent().getSessionScope().map.get("User_Pref_Info"); return info.getLocale(); }
Note:
The handler class must have a constructor with no arguments, or uses the default Java constructor.
Add an initialization parameter to configure the user preference handler, as described in Table 102.
Configuring Locale User Preference Value Enter the name of the initialization parameter as follows UserPreferences.Handler
Value 3. 4.
Save the web.xml file. Rebuild and restart your Fusion web application.
<servlet> <servlet-name>adfdiRemote</servlet-name> <servlet-class> oracle.adf.desktopintegration.servlet.DIRemoteServlet </servlet-class> <init-param> <param-name>UserPreferences.Handler</param-name> <param-value>myCompany.XYZ.CustomUserPrefsHandler</param-value> </init-param> </servlet>
11
11
Section 11.1, "About Security In Your Integrated Excel Workbook" Section 11.2, "Authenticating the Excel Workbook User" Section 11.3, "Checking the Integrity of an Integrated Excel Workbook's Metadata" Section 11.4, "What You May Need to Know About Securing an Integrated Excel Workbook" Section 11.5, "Authorizing the Excel Workbook User"
If you click Yes to connect, another dialog prompts you to enter the credentials, as shown by the example in Figure 112.
Figure 112 Dialog to verify End User's Credentials
The dialog that is shown in Figure 112 might be different as it depends on how the Fusion web application is configured to enforce authentication. For example, if Form-based authentication is being used by the web application, then the end-user will see a browser dialog with a web page with fields for user name and password.
11.1.2 Additional Functionality for Integrated Excel Workbook in a Secure Fusion Web Application
After you have secured your integrated Excel workbook, you may find that you need to add additional functionality for your workbook. Following are links to other functionalities that you can use:
Validating integrated Excel workbook: You can configure server-side and client-side validation for the Fusion web application and the integrated Excel workbook. For more information, see Chapter 12, "Adding Validation to an Integrated Excel Workbook."
Testing integrated Excel workbook: Before publishing and deploying your integrated Excel workbook, you must test it. For more information, see Chapter 13, "Testing Your Integrated Excel Workbook." Publishing and deploying integrated Excel workbook: The final step after you design and validate your integrated Excel workbook is to publish and deploy it. For more information, see Chapter 14, "Deploying Your Integrated Excel Workbook."
The end user enters user credentials and, assuming these are valid, an authenticated session is created and assigned to the client (the web browser control hosted by the Excel workbook).
Note: If the Login method is invoked when a session has already been established, it first invokes the Logout action internally to free that session.
After logging out, the user must log in again to upload or download data. If two or more workbooks are open (in test or runtime mode) and running against the same Fusion web application, closing one workbook does not initiate the logout mechanism. The user continues to stay logged in and may continue to work on remaining open workbooks, and can open the closed workbook without being asked for credentials again. The user is logged out when all workbooks running against the same Fusion web application are closed.
In the Workbook group of the Oracle ADF tab, click Workbook Properties. In the Edit Workbook Properties dialog, click the Reset WorkbookID link. Click Yes to confirm and reset the WorkbookID workbook property in the dialog that appears., as shown in Figure 115.
5.
Click OK.
What You May Need to Know About Securing an Integrated Excel Workbook
11.4 What You May Need to Know About Securing an Integrated Excel Workbook
Note the following points about securing an integrated Excel workbook with a Fusion web application:
Data security If you save an Excel workbook containing data downloaded from a Fusion web application to a location, such as a network directory, where other users can access the Excel workbook, the data stored in the Excel workbook is accessible to other users.
Security in Microsoft Excel You can enhance the security of an integrated Excel workbook using Excel's functionality to set a password on a workbook. It prevents unauthorized users from opening or modifying the workbook. For more information about Excel security features, see Excel's documentation.
Integrated Excel workbooks can be configured to cache data, as described in Section 15.2, "Restore Server Data Context Between Sessions." Make sure that you do not cache sensitive data in the integrated Excel workbook. If the Fusion web application is running on the https protocol, you may receive a certificate error while connecting from an integrated Excel workbook. You can either install the required certificate using Microsoft Internet Explorer, or choose to continue to log in and connect to the web application. End users that download integrated Excel workbooks using Microsoft Internet Explorer may be prompted unexpectedly for credentials before the Excel application is visible, and then prompted again once the workbook opens. This may occur when the web application is configured to use certain authentication methods like Basic or Digest. The extra prompt is due to Excel making an OPTIONS request on the web directory containing the workbook. To avoid the extra login prompt, end users can choose to save the workbook locally instead of opening it directly from the browser.
For a non-authenticated Fusion web application, end-users will not be prompted to log in. However if the application uses the https protocol, then end users may briefly see a login dialog appear when the first connection is established to the web application. Workbook developers can control the size of the dialog with the Workbook.Login.WindowSize property.
If you are an administrator, you should also see the "What You May Need to Know About Configuring Security in a Fusion Web Application" section in Administering Oracle ADF Applications.
allow end users to interact with the integrated Excel worksheet, assign them the roles that have been granted access to the page definition. If you have upgraded ADF Desktop Integration from an old version, you may need to review the resource grants for all of the page definitions that are used with integrated Excel worksheets. For example, if your Fusion web application supports authorization, and you have a page definition myWorksheetPageDef.xml that has no resource grants and is used by one (or more) integrated Excel worksheets, then you need to assign end users the roles that have been granted access to the page definition. When transitioning to the new version of ADF Desktop Integration, you may find it helpful to temporarily create resource grants for the worksheet page definitions that are granted to authenticated-role, or some other generic role, allowing you to run those worksheets as before while you fine tune your roles and resource associations. For more information about authorization, roles, and resource grants, see the "Enabling ADF Security in a Fusion Web Application" chapter in the Developing Fusion Web Applications with Oracle Application Development Framework. ADF Desktop Integration does not enforce authorization of other resource types, such as entity object-level, entity attribute-level, ADF Method, Insert while New, Panel Tab, and Task Flow authorization.
Note:
You can configure resources and grants from the Resource Grants page of the overview editor for the jazn-data.xml file. For more information, see the "Defining ADF Security Policies" section in the Developing Fusion Web Applications with Oracle Application Development Framework. On an authorization failure, the end user receives an error message, such as the following, and ADF Desktop Integration in the worksheet is disabled: ADFDI-05589 You are not authorized to use this worksheet for interacting with the Fusion web application.
11.5.1 What You May Need to Know About ADF Desktop Integration-Disabled Worksheet
The following limitations apply to an ADF Desktop Integration-disabled worksheet:
All ADF buttons, worksheet-level ribbon commands, and worksheet-level events are disabled. If the authorization failure occurs during worksheet initialization, no form labels, table column headers, or buttons are drawn on the worksheet. If the authorization failure occurs for an initialized worksheet, all ADF buttons are disabled, but other worksheet components (such as ADF Input Text and ADF Table) are not affected and are left visually unchanged. End user can perform standard Excel interactions on the disabled worksheet. The user may alter the data in an ADF Table component in the worksheet, but the Changed column will not be updated. There is no impact on workbook-level commands. End users can continue to use the following commands: Login, Logout, About, Edit Options, and Clear All Data.
An ADF Desktop Integration-disabled worksheet is automatically enabled when the end user reopens the integrated Excel workbook and establishes a new session,
provided the new session is authorized. Logging out, and then logging in again, also re-enables ADF Desktop Integration in a disabled integrated Excel worksheet.
12
12
Section 12.1, "About Adding Validation to an Integrated Excel Workbook" Section 12.2, "Providing Server-Side Validation for an Integrated Excel Workbook" Section 12.3, "Providing Client-Side Validation for an Integrated Excel Workbook" Section 12.4, "Error Reporting in an Integrated Excel Workbook" Section 12.5, "Providing a Row-by-Row Status on an ADF Table Component" Section 12.6, "Adding Detail to Error Messages in an Integrated Excel Workbook" Section 12.7, "Handling Data Conflicts When Uploading Data from a Workbook"
Testing integrated Excel workbook: Before publishing and deploying your integrated Excel workbook, you must test it. For more information, see Chapter 13, "Testing Your Integrated Excel Workbook." Publishing and deploying integrated Excel workbook: The final step after you design and validate your integrated Excel workbook is to publish and deploy it. For more information, see Chapter 14, "Deploying Your Integrated Excel Workbook."
Note:
Excel displays error messages when a validation fails; these error messages cannot be localized. ADF Desktop Integration does not support server-side validation warnings. Validation warnings, set for rules defined in the Fusion web application, are not displayed by the integrated Excel workbook.
For more information about data validation in Excel, see Excel's documentation.
At runtime, the previous error message summary is cleared (if one existed) when the action set starts the invocation. If no errors occur during invocation, error message remains blank. If an error occurs, the ADF Output Text component displays the error message summary. An alternative approach to returning error message summaries generated by action sets invoked on a worksheet is to set #{worksheet.errors} as the value for an action set's Alert.FailureMessage property. This approach displays the generated error message summary in a dialog. Components such as the ADF Table and ADF Read-only Table components that have actions which interact with the Fusion web application can also return error message summaries. Set the following EL expression for the Value property of the ADF Output Text component or for an action set's Alert.FailureMessage property:
#{components.componentID.errors}
where componentID refers to the ID of the component (ADF Table or ADF Read-only Table component) that invokes the action. The EditCustomers-DT.xlsx file in the Summit sample application for ADF Desktop Integration demonstrates how to return error message summaries generated
by action sets invoked on a worksheet and by the actions of an ADF Table component. Figure 122 shows these EL expressions in design mode.
Figure 122 EL Expressions to Return Error Messages in an ADF Output Text Component
Worksheet's DisplayWorksheetErrors action To display a worksheet's error messages, configure the action set of a component on the worksheet or the worksheet ribbon button to invoke this action. For example, Figure 123 shows the Edit Component: ADF Output Text dialog configuring the DisplayWorksheetErrors action as a DoubleClickActionSet item for an ADF Output Text component on the worksheet.
At runtime, double-clicking the ADF OutputText component invokes the DisplayWorksheetErrors action as shown in Figure 124.
For more information about the Worksheet's DisplayWorksheetErrors action, see Section A.13, "Worksheet Actions and Properties."
ADF Table component's DisplayRowErrors action To display row-level failures that occur in an ADF Table component, invoke this action. Row-level failures occur when end user invokes the following actions: Upload DeleteFlaggedRows DoubleClickActionSet invoked from an ADF Table component column
For more information about using this action, see Section 12.5, "Providing a Row-by-Row Status on an ADF Table Component."
ADF Table component's DisplayTableErrors action To display table-level failures that occur in an ADF Table component, invoke this action. It is not intended that an ADF Table component column's DoubleClickActionSet invoke this action. Instead add this action to an action set that returns error messages to end users when failures occur during invocation of the action binding specified by an ADF Table component's BatchOptions.CommitBatchActionID property. At runtime, double-clicking the ADF OutputText component invokes the DisplayTableErrors action as shown in Figure 125.
For more information about ADF Table component actions, see Section A.9, "ADF Table Component Properties and Actions."
The ADF Table component populates the _ADF_StatusColumn column with the status for each row following the invocation of the ADF Table component action. For example, it populates the _ADF_StatusColumn column with the upload status for each row following the invocation of the ADF Table component's Upload action. Figure 126 shows rows in an ADF Table component where the values in those rows have been changed, as indicated by the upward pointing arrows in the Changed column. In the ZipCode column, a text value has been entered where a number value is expected.
Figure 126 ADF Table Component with Changed Rows Before Upload
Figure 127 shows the same rows in the ADF Table component after invocation of the ADF Table component's Upload action. The ADF Table component populates the _ ADF_StatusColumn column (labeled Status in this example at runtime) with a message indicating whether the row updated successfully or not.
Figure 127 ADF Table Component with Changed Rows After Upload
By default, the _ADF_StatusColumn column's DoubleClickActionSet is configured to invoke the ADF Table component's DisplayRowErrors action. When end users double-click a row in this column at runtime, the ADF Table component invokes the DisplayRowErrors action. This action displays a dialog with a list of errors for that row if errors exist. If no errors exist, the dialog displays a message to indicate that no errors occurred. Figure 128 shows the dialog that appears if the end user double-clicks the cell in Figure 127 that displays Update failed in the Status column.
For more information about the _ADF_StatusColumn column, see Section 7.12, "Special Columns in the ADF Table Component."
workbook across multiple sessions. For information about flagging rows, see Section 7.11.2, "Row Flagging in an ADF Table Component." For information about invoking component actions, see Section 8.2.2, "How to Invoke Component Actions in an Action Set." For more information about the components that the ADF Table component supports, see Section A.9, "ADF Table Component Properties and Actions."
12.7.1 How to Configure a Workbook to Handle Data Conflicts When Uploading Data
You specify a row-specific attribute of the tree binding for the RowData.ChangeIndicatorAttribute property to determine whether a row has been modified by another user since the row was last downloaded by the ADF Table component. To configure a workbook to handle data conflicts: 1. Open the integrated Excel workbook.
2. 3.
Select any cell of the ADF Table component and click Edit Properties in the Oracle ADF tab. In Edit Component: ADF Table dialog, for the RowData.ChangeIndicatorAttribute property, specify the row-specific attribute of the tree binding that you use to determine whether a row has been modified by another user since the row was last downloaded by the ADF Table component in your integrated Excel workbook. Click OK.
4.
13
13
Section 13.1, "About Testing Your Integrated Excel Workbook" Section 13.2, "Testing Your Fusion Web Application" Section 13.3, "Validating the Integrated Excel Workbook Configuration" Section 13.4, "Testing Your Integrated Excel Workbook" Section 13.5, "Running a Server Ping Test"
Validating the integrated Excel workbook Running the integrated Excel workbook in test mode
Publishing your integrated Excel workbook: After you test and validate your workbook, you must publish it. For more information see, Section 14.3, "Publishing Your Integrated Excel Workbook." Deploying your integrated Excel workbook: After you publish your workbook, you may wish to deploy it with your Fusion web application. For more information, see Section 14.4, "Deploying a Published Workbook with Your Fusion Web Application." Working in disconnected mode: After downloading data to the integrated Excel workbook, sometimes end users may need to use the workbook when a server connection may not be available, or after the server session has expired. For more information, see Section 15.1, "About Disconnected Workbooks."
If you make changes to the Fusion web application to resolve problems identified by testing the application, you need to:
Close Excel and all integrated Excel workbooks. The application deployment may fail if it encounters locked files, as Excel locks the files that it opens. Rebuild the JDeveloper project where you develop the Fusion web application. Run the Fusion web application. Reload the page definition files that are associated with the integrated Excel workbook. Click the Refresh Bindings button in Oracle ADF tab of the integrated Excel workbook to reload the page definition files.
These steps make sure that the changes in the Fusion web application are available to the integrated Excel workbook. For information about how to reload a page definition file, see Section 4.3.3, "How to Reload a Page Definition File in an Excel Workbook."
In your integrated Excel workbook, click the Oracle ADF tab. In the Test group, click Validate. The Configuration Validation dialog appears listing all your warnings and errors.
4.
If any warning or error is displayed, click to select it. A description of the warning or error message is displayed in the dialog. For example, Figure 132 illustrates a validation failure message of an invalid EL expression.
You may continue to keep the Configuration Validation dialog open while you resolve the validation failures. To verify whether you have resolved an error or a warning, click Revalidate to run the validation rules again.
13.3.2 What Happens When You Validate the Integrated Excel Workbook Configuration
When you validate the workbook at design time, ADF Desktop Integration validates all workbook configuration properties, including worksheet and worksheet component properties, against defined validation rules. Any and all validation failures (errors and warnings) are listed in the Configuration Validation dialog. Each validation failure, when selected, provides contextual information about the failure, and provides enough detail to locate and fix each validation failure. The Configuration Validation dialog provides the following information for each validation failure:
Severity type (error or warning) Name of the worksheet. The word Workbook is displayed if the validation failure does not correspond to a particular worksheet. Worksheet component ID ("Workbook" or "Worksheet" if the validation failure does not correspond to a particular worksheet component) Property containing the validation failure Description of the validation failure (error or warning)
When you select a specific failure entry in the dialog, the dialog displays additional details about the failure including:
Certain validation rules may result in multiple distinct failures. For example, when an expression is being validated, different validation failures occur based on expression type, expression syntax, or the location in which the property is exposed in the workbook configuration. For example, consider the following expression value: #{bindings.EmpView1.hints.Empno.label} The expression value is legal when used within a column header label inside of a table component, but the same expression value is illegal when specified as part of the Worksheet.Title expression.
Note: If Enabled is set to False for a group of workbook configuration properties, validation of other property values within the same group is skipped.
Identify the component that gave the error or warning message. In Figure 132, note that the ADF Output Text component generated the error. In the worksheet, search for Output Text component that uses #{worksheet.error s} expression.
2. 3. 4.
Open the property editor of the component. Navigate to the invalid property value identified by the full property context path. Edit the property value to resolve the validation failure.
Figure 133 illustrates the ADF OutputText component property editor and its invalid EL expression.
Figure 133 Resolving Validation Failure
5. 6.
Revalidate the workbook to verify whether the validation failure has been resolved. Click Revalidate to run the validation rules again. After fixing all validation failures, click Close to close the Configuration Validation dialog. Figure 134 illustrates the Configuration Validation dialog with no warnings or error messages.
13.3.4 How to Log the Integrated Excel Workbook Configuration Validation Failures at Runtime
By default, there is no runtime validation of integrated Excel workbook configuration. However, you may log validation failures at runtime by setting the client log level to
Error or Warning. For more information about enabling client-side logging, see Section C.3.2, "About Client-Side Logging."
Does not display the connection confirmation Displays the connection confirmation dialog dialog Displays the Oracle ADF ribbon tab Allows you to switch back to design mode Does not display Oracle ADF tab Does not allow you to switch back to design mode
ADF Desktop Integration can generate log files that capture information based on events triggered by an integrated Excel workbook. For more information about these log files, see Appendix C, "Troubleshooting an Integrated Excel Workbook."
Note:
that:
The Fusion web application is running. The ping to server is successful, and the server is configured for ADF Desktop Integration. The ADF Desktop Integration version of the server and the client are same, or compatible. Note that an older client (version X) works fine with the newer server (version X+1) during the transition period, but an older server (version X) may not work with a newer client (version X+1).
To run an integrated Excel workbook in test mode: To test and run an integrated Excel workbook, click the Run button on the Oracle ADF tab.
The integrated Excel workbook switches to test mode from design mode. Before starting the test mode, ADF Desktop Integration clears all design time component placeholders. To stop test mode and return the integrated Excel workbook to design mode: In the integrated Excel workbook that you are testing, click the Stop button on the Oracle ADF tab. The integrated Excel workbook switches to design mode from test mode. Before switching back to design mode, ADF Desktop Integration removes all visible and cached data from all parts of the workbook, and then redraws the design time component placeholders.
Note:
When the end user tries to close the integrated Excel workbook, Microsoft Excel prompts a dialog to save the workbook even if the end user has not modified it after opening it. This behavior is expected because ADF Desktop Integration modifies an integrated Excel workbook each time the end user opens it.
Note:
A valid user session is required to run the server ping test. If authentication is enabled for the web application, you will be prompted for valid credentials to log in.
14
14
Section 14.1, "About Deploying Your Integrated Excel Workbook" Section 14.2, "Making ADF Desktop Integration Available to End Users" Section 14.3, "Publishing Your Integrated Excel Workbook" Section 14.4, "Deploying a Published Workbook with Your Fusion Web Application" Section 14.5, "Passing Parameter Values from a Fusion Web Application Page to a Workbook"
Set up ADF Desktop Integration on their systems. Make the ADF Desktop Integration setup.exe tool available to end users from, for example, a directory on your network. For more information, see Section 14.2, "Making ADF Desktop Integration Available to End Users."
When you deploy your integrated Excel workbook with your Fusion web application, you are not required to provide the download URL of workbooks explicitly. The end users can download the integrated Excel workbooks from the Fusion web application's user interface. For more information, see Section 14.4, "Deploying a Published Workbook with Your Fusion Web Application."
Passing Parameters: You can configure a page in your Fusion web application to pass parameter values to an integrated Excel workbook when the end user downloads the workbook from the page. For more information, see Section 14.5, "Passing Parameter Values from a Fusion Web Application Page to a Workbook." Disconnected Workbooks: End users can use your integrated Excel workbooks when there is no connectivity with the Fusion web application. For more information, see Chapter 15, "Using an Integrated Excel Workbook Across Multiple Web Sessions and in Disconnected Mode."
For information about using the installation program, see the "Making the Runtime Edition of ADF Desktop Integration Available to Multiple End Users" section in Administering Oracle ADF Applications.
After publishing one or more workbooks, you should restart the Fusion web application in order for those workbooks to be downloaded and opened successfully in Microsoft Excel. If the web application is not restarted, you might get errors, such as the following: TampercheckErrorException: ADFDI-05537: The integrity of the workbook integration could not be determined.
Ensure that the ApplicationHomeFolder and WebPagesFolder properties in the Edit Workbook Properties dialog are correct. If these properties are not set, ADF Desktop Integration prompts to set them when you publish the integrated Excel workbook. For more information, see Section 4.2.2, "How to Configure a New Integrated Excel Workbook."
3. 4.
In the Oracle ADF tab, click the Publish button. Specify the directory and file name for the published workbook in the Publish Workbook dialog that appears, as shown in Figure 141. The directory and file
Deploying Your Integrated Excel Workbook 14-3
name that you specify for the published workbook must be different from the directory and file name for the design time workbook.
5.
14.3.2 How to Publish an Integrated Excel Workbook Using the Command Line Publish Tool
The publish tool is run from the command line, and is available in the MW_ HOME\jdeveloper\adfdi\bin\excel\tools\publish directory as publish-workbook.exe. Before you run the publish tool, open the source integrated Excel workbook and ensure that the ApplicationHomeFolder and WebPagesFolder properties in the Edit Workbook Properties dialog are correct.
Note: You cannot publish a workbook that is already published, or is in runtime mode.
Before you begin: It may be helpful to have an understanding about how to publish your integrated Excel workbook. For more information, see Section 14.3, "Publishing Your Integrated Excel Workbook." You may also find it helpful to understand functionality that can be added using other ADF Desktop Integration features. For more information, see Section 14.1.2, "Additional Functionality for Deploying Your Integrated Excel Workbook." Now, navigate to MW_HOME\jdeveloper\adfdi\bin\excel\tools\publish directory and run the publish tool using the following syntax: publish-workbook -workbook (-w) <source-workbook-path> -out (-o) <destination-workbook-path> where source-workbook-path is the full path of the source workbook, and destination-workbook-path is the full path where the published workbook is saved. For example: publish-workbook -workbook D:\Application1\Project1\ViewController\src\oracle\sampledemo\ex cel\workbook-src.xlsx -out D:\Application1\Project1\ViewController\public_ html\excel\published\workbook.xlsx
Tip: For more information about the arguments required by the publish tool, run the following command:
Notes:
Always specify the absolute paths of the source and destination workbooks. The publish tool does not support relative paths of the workbooks. The destination workbook cannot have the same name as the source, even if the workbook paths are different.
After publishing the integrated Excel workbook successfully, the publish tool displays a success message. If there is any error while publishing the workbook, the publish tool aborts the process and the error messages are displayed on the command line console. If you are using the command line publish tool, note that by default the publish tool logs messages to the command line console at information level. Using the Publish Tool with ANT You can create ANT scripts to run the publish tool from JDeveloper when you build your Fusion web application. You can use either of the following methods to run the utility using ANT:
Generate an ANT build script for the project and add a target to run the workbook command line publish tool Generate or create a separate ANT build script for running the workbook command line publish tool
A sample ANT build script (publish-workbook.xml) to run the publish tool is available in the MW_HOME\jdeveloper\adfdi\bin\excel\samples directory. The sample ANT script demonstrates the invocation of the command-line workbook publishing tool.
Validates the mandatory workbook settings. Updates the client registry. For more information, see Section 11.3, "Checking the Integrity of an Integrated Excel Workbook's Metadata." Creates the published workbook with the specified file name in the specified directory. Publish also exports the workbook definition. The published workbook definition XML file is saved at the same location as the design-time copy of the workbook. For more information about workbook definition, see Section 5.15, "Exporting and Importing Excel Workbook Integration Metadata."
4. 5. 6. 7.
Clears the ApplicationHomeFolder, WebAppRoot, and WebPagesFolder properties from the workbook settings of the published workbook. Removes binding expressions that are visible in the worksheet while the workbook is in design mode. Changes the mode of the workbook to runtime mode. Inserts a Publishing Timestamp property into the workbook. This property is visible in the Properties tab of About dialog.
<Summit_HOME>\ViewController\public_html\excel where Summit_HOME is the installation directory for the Summit sample application for ADF Desktop Integration. After you decide on a location to store your integrated Excel workbooks, you can configure web pages in your Fusion web application allowing end users to access the integrated Excel workbooks. For example, Figure 142 shows Internet Explorer's File Download dialog, which was invoked by clicking the Available Demos > Editable Table Sample menu option on the index.jspx page of the Summit sample application for ADF Desktop Integration.
Figure 142 Invoking an Integrated Excel Workbook from a Fusion Web Application
To enable the functionality illustrated in Figure 142, the HTTP filter parameters for your Fusion web application must be configured to recognize Excel workbooks. JDeveloper automatically configures these parameters for you ADF Desktop Integration is enabled in the Fusion web application. If you want to manually configure the HTTP filter parameters, see Appendix D, "ADF Desktop Integration Settings in the Web Application Deployment Descriptor." After you have configured the HTTP filter for your Fusion web application, you configure the web pages that the Fusion web application displays to end users to allow them to invoke Excel workbooks. A basic method of invoking an Excel workbook that you have integrated with a Fusion web application is to provide a hyperlink that invokes the workbook. For example, you could write the following HTML in a web page: <a href="/excel/EditCustomers.xlsx">Editable Table Sample</a> where excel is a subdirectory of the directory specified by the WebPagesFolder workbook property and EditCustomers.xlsx is the Excel workbook that the end user invokes.
You can provide functionality that allows end users to invoke Excel workbooks from buttons, lists, and ribbon commands. The following list provides some examples:
Button Display a button on the web page that, when clicked, invokes the integrated Excel workbook.
Selection list Use the ADF Faces selectOneChoice component with a button to invoke an integrated Excel workbook.
Menu Use the ADF Faces goMenuItem component. The Available Demos menu, as illustrated in Figure 142, uses the goMenuItem component. The following entry appears in the index.jspx page of the Summit sample application for ADF Desktop Integration and demonstrates the goMenuItem component:
<af:goMenuItem text="Editable Table Sample" id="gmi1" destination="/excel/EditCustomers.xlsx"/>
For more information about creating web pages for a Fusion web application, see the Developing Web User Interfaces with Oracle ADF Faces.
The DIExcelDownloadFilter filter is defined. Filter mappings are defined for *.xlsx files.
When the end user makes an http request for a workbook (for example, user clicks a link in a web page from the application), the DIExcelDownloadFilter filter embeds the WebAppRoot property into the workbook as it gets streamed back as the http response. The WebAppRoot property is later used by the ADF Desktop Integration client to connect to the Fusion web application, establish a user session, and send data back and forth. The DIExcelDownloadFilter filter constructs the WebAppRoot value from the current HttpServletRequest object that is passed in to the doFilter() entry point. The filter code calls HttpServletRequest.getRequestURL()and gets the "root" portion of the full URL by removing everything after the context path portion (uses HttpServletRequest.getContextPath()).
14.5 Passing Parameter Values from a Fusion Web Application Page to a Workbook
You can configure a page in your Fusion web application to pass parameter values to an integrated Excel workbook when the end user downloads the workbook from the page. For example, if the end user attempts to download a workbook from a page that displays a list of products, the list of products that appears in the workbook corresponds to the list of products displayed in the page when the end user invoked the download. Subsequent changes that the end user makes to data in one location (the worksheet or the Fusion web application's page) do not affect data in the other location.
Deploying Your Integrated Excel Workbook 14-7
Verify that the HTTP filter is configured to allow end users to download integrated Excel workbooks from the Fusion web application. By default, JDeveloper configures the HTTP filter with appropriate values when you enable ADF Desktop Integration in a project. To verify the parameter values of the HTTP filter, see Section D.2, "Configuring the ADF Desktop Integration Excel Download Filter." Configure the page in your Fusion web application from which the end user downloads the integrated Excel workbook so that it passes its parameters through URL arguments to the integrated Excel workbook when the end user downloads it. Configure the page definition file associated with the worksheet in the integrated Excel workbook so that the worksheet is initialized with the parameters from the page in the Fusion web application from which the end user downloads the workbook. Configure workbook and worksheet properties in the integrated Excel workbook that end users download so that the workbook contains the parameters from the page in the Fusion web application from which the end user invokes download.
14.5.1 How to Configure the Fusion Web Application's Page to Pass Parameters
You insert an <af:link> tag and specify property values for it that reference the integrated Excel workbook the end user downloads and the values to download. You also specify the commands on the page that, when invoked, require the Fusion web application to refresh the values referenced by the <af:link> tag and its property values. Before you begin: It may be helpful to have an understanding of how to pass parameter values from the Fusion web application to the integrated Excel workbook. For more information, see Section 14.5, "Passing Parameter Values from a Fusion Web Application Page to a Workbook." You may also find it helpful to understand functionality that can be added using other ADF Desktop Integration features. For more information, see Section 14.1.2, "Additional Functionality for Deploying Your Integrated Excel Workbook." To configure the page in the Fusion web application: 1. In JDeveloper, insert the af:link tag into the page from which the end user downloads the integrated Excel workbook.
2. 3.
In the Structure window, right-click the af:link node and choose Go to Properties. Expand the Common section and set values for the properties, as described in Table 141.
Properties for af:link Tag Value Write the text that appears to end users at runtime. For example, write text such as the following to appear at runtime: Download to Excel
Table 141 (Cont.) Properties for af:link Tag Property Destination Value Invoke the expression builder to write an EL expression that specifies the integrated Excel workbook and the values to download as a URL argument: For example, write an EL expression such as the following: "/excel/workbook.xlsx?productName=#{bindings.productNam e.attributeValue}" Note that the runtime URL-encoded value of the entire query string to the right of ? must be less than 2048 bytes. If the runtime value exceeds 2048 bytes, the integrated Excel workbook will contain only the URL arguments that fit in 2048 bytes. Subsequent URL arguments do not get included with the integrated Excel workbook. Instead, the Fusion web application writes log entries for these URL arguments identifying them as having not been included. For example, the total size of the result when the following EL expression is evaluated and then URL-encoded must be less than 2048 bytes. productName=#{bindings.productName.attributeVal ue}&productType=#{bindings.productType.attribut eValue}. Also note that if the URL contains more than 256 characters, an exception is raised when the end user downloads and opens the integrated Excel workbook without saving it. To resolve this problem, you must limit your URL length to 256 characters, or instruct the end user to save the workbook before opening it. 4.
Optionally, expand the Behavior section and specify component IDs for the partialTriggers property that, when invoked, update the values of the af:link tag and its Destination property. For example, if you have navigation buttons with the IDs NextButton, PreviousButton, FirstButton, and LastButton, specify them as follows: :NextButton :PreviousButton :FirstButton :LastButton
5.
Save the page. The following example shows the entries that JDeveloper generates in a JSF page using the examples in this procedure:
<af:link text="Download to Excel" destination="/excel/workbook.xlsx?productName=#{bindings.productName.attributeV alue}" partialTriggers=":NextButton :PreviousButton :FirstButton :LastButton"/>
14.5.2 How to Configure the Page Definition File for the Worksheet to Receive Parameters
You configure the page definition file associated with the worksheet in the integrated Excel workbook as follows:
Add one or more parameter elements that initialize the worksheet with the values specified by the workbook Parameters property that you configure in Section 14.5.3, "How to Configure Parameters Properties in the Integrated Excel Workbook."
The following example shows a parameter element in a page definition file that is associated with a worksheet in an integrated Excel workbook:
<parameters> <parameter id="ProductNameParam" /> </parameters>
Add an invokeAction and a method action binding so that the page definition file associated with the worksheet initializes correctly.
Note:
When a page definition file that has an invokeAction is used with an integrated Excel workbook, the method that is used in the invokeAction may be invoked multiple times. If needed, the method should be coded to handle these multiple invocations. The Refresh and RefreshCondition properties of the <invokeAction> element can also be configured to manage the frequency of invocation.
The following example shows the initializeProductTable invokeAction invoking the filterByProductName method action binding. The invokeAction is refreshed only when a value for ProductNameParam is supplied.
<executables> <invokeAction Binds="filterByProductName" id="initializeProductTable" Refresh="deferred" RefreshCondition="${bindings.ProductNameParam != null}"/> ... </executables>
The method action binding invokes a view object method (filterByProductName). The view object method takes a single String argument (ProductNameArg) that references the value of ProductNameParam.
<bindings> <methodAction id="filterByProductName" RequiresUpdateModel="true" Action="invokeMethod" MethodName="filterByProductName" IsViewObjectMethod="true" DataControl="AppModuleDataControl" InstanceName="AppModuleDataControl.ProductVO1"> <NamedData NDName="ProductNameArg" NDValue="${bindings.ProductNameParam}" NDType="java.lang.String"/> </methodAction> . . . </bindings>
For more information about configuring a page definition file, see Section 4.3, "Working with Page Definition Files for an Integrated Excel Workbook."
Before you begin: It may be helpful to have an understanding of how to pass parameter values from the Fusion web application to the integrated Excel workbook. For more information, see Section 14.5, "Passing Parameter Values from a Fusion Web Application Page to a Workbook." You may also find it helpful to understand functionality that can be added using other ADF Desktop Integration features. For more information, see Section 14.1.2, "Additional Functionality for Deploying Your Integrated Excel Workbook." To configure the workbook Parameters property: 1. Open the integrated Excel workbook.
2. 3. 4.
In the Workbook group of the Oracle ADF tab, click Workbook Properties. Click the browse (...) icon beside the input field for Parameters to invoke the Edit Parameters dialog. Click Add to add a new workbook initialization parameter and configure its properties as follows:
(Optional) In the Annotation field, enter a description of the workbook initialization parameter. In the Parameter field, specify the name of the URL argument that you configured for the af:link tag's Destination property as described in Section 14.5.1, "How to Configure the Fusion Web Application's Page to Pass Parameters." For example, if you added the af:link URL argument as described in Table 141, the Parameter property value would be productName, as illustrated in Figure 143.
5. 6.
Repeat Step 4 as necessary to add other workbook initialization parameters. Click OK. For more information about the workbook Parameters property, see Table A18.
1.
To configure the worksheet Parameters property: Open the integrated Excel workbook.
14-11
2. 3. 4.
In the Workbook group of the Oracle ADF tab, click Worksheet Properties. Click the browse (...) icon beside the input field for Parameters to invoke the Edit Parameters dialog. Click Add to add a new worksheet parameter and configure it as in Figure 144:
(Optional) In the Annotation field, enter a description of the worksheet parameter. In the Parameter field, specify a parameter element that you added to the page definition file associated with the worksheet, as described in Section 14.5.2, "How to Configure the Page Definition File for the Worksheet to Receive Parameters." In the Value field, write an EL expression that references the value of the Parameter property you specified for the workbook initialization parameter (workbook Parameters array). Use the following syntax when writing the EL expression: #{workbook.params.parameter} where parameter references the value of the Parameter property you specified for the workbook initialization parameter.
5. 6.
Repeat Step 4 as necessary to add other workbook initialization parameters. Click OK. For more information about the worksheet Parameters property, see Table A19.
By default, the workbook parameters are not sent every time the workbook connects to the server to request metadata, the end user logs out, or the session expires. If required, you can configure the workbook to send the initialization parameters by configuring the SendParameters property. To configure the worksheet SendParameters property: 1. Open the integrated Excel workbook.
2. 3.
In the Workbook group of the Oracle ADF tab, click Worksheet Properties. In the Edit Worksheet Properties dialog, set the value of SendParameters as shown in the Table 142 and Figure 145:
Table 142
SendParameters Property This value... True to send workbook parameters when the workbook connects to the server to request metadata or data. When set to True, parameters are sent every time when the metadata is requested and the first time when data is requested, during each user session. False is the default value. For more information, see Section 15.2, "Restore Server Data Context Between Sessions."
4.
Click OK.
14.5.4 What Happens at Runtime: How Parameters Are Passed from a Fusion Web Application to the Integrated Excel Workbook
When the end user downloads the integrated Excel workbook from the Fusion web application, the af:link tag is evaluated and the current product name is captured and included on the URL. The adfdiExcelDownload filter embeds the names and values of all the parameters from the URL into the downloaded integrated Excel workbook. After downloading the workbook, when the end user opens it for the first time, the active worksheet of the integrated Excel workbook is initialized. The initialization process includes fetching metadata from the web application. As part of retrieving the worksheet metadata, the stored workbook parameters (if any) are sent to the ADF Desktop Integration remote servlet and are available for application logic such as <invokeAction> executables. Specifically, the parameters are set into BindingContainer DCParameters before the binding container is refreshed. The action set in the worksheet Startup event is also executed during initialization. After initialization, the initialization status for each worksheet is recorded when the integrated Excel workbook is saved to disk. After the integrated Excel workbook has been saved, closed, and reopened , the first-time initialization is skipped for any worksheets that were previously initialized. If workbook parameters were captured when the integrated Excel workbook was first downloaded, and those parameters are required to set up server context, then the Worksheet.ServerContext.SendParameters property should be set to True. When the SendParameters property is True, workbook parameters are sent on every request for metadata, and also on the first request for data in each user session.
Deploying Your Integrated Excel Workbook 14-13
To reset the initialization state for all worksheets in the workbook, invoke the ClearAllData action. For more information about the ClearAllData action, see Table A17.
Note:
Parameter values passed to the server might reset when a web dialog is invoked in an action set where the ShareFrame property is True. Custom code, which uses the parameters and requires that values be maintained across the invocation of a web dialog, should ensure that those values are saved in the user session data structures.
15
15
Using an Integrated Excel Workbook Across Multiple Web Sessions and in Disconnected Mode
This chapter describes how to configure the integrated Excel workbook so that your use cases work properly across multiple web application sessions. This chapter includes the following sections:
Section 15.1, "About Disconnected Workbooks" Section 15.2, "Restore Server Data Context Between Sessions" Section 15.3, "Caching of Static Information in an Integrated Excel Workbook" Section 15.4, "Caching Lists of Values for Use in Disconnected Mode"
Modify data downloaded from the Fusion web application Insert new data into the appropriate ADF Table component contained in the workbook Save changes to data and close and reopen the workbook without having to upload data to the Fusion web application Track and update changes in the ADF Table component
Using an Integrated Excel Workbook Across Multiple Web Sessions and in Disconnected Mode 15-1
Troubleshooting integrated Excel workbook: You might encounter some problems while developing or deploying an integrated Excel workbook. For more information, see Appendix C, "Troubleshooting an Integrated Excel Workbook." Installing runtime edition of ADF Desktop Integration: You must install the runtime edition of ADF Desktop Integration to enable end users to use ADF Desktop Integration and integrated Excel workbooks. For more information, see Appendix H, "End User Actions."
The end user makes changes to data in a workbook, saves and closes the workbook, reopens the workbook at a later time, and attempts to upload the changes he or she made before saving and closing the workbook. The time between invocation of an ADF Table component's Download and Upload actions (or some other ADF Table component action that contacts the Fusion web application) exceeds the session timeout value specified for a Fusion web application session.
Both the scenarios described in the previous list involve two sessions. The first session is assigned when the end user opens an integrated Excel workbook and logs on to the Fusion web application. The Fusion web application terminates this session when the end user logs off from the Fusion web application or when the session expires. The Fusion web application assigns a second session when the end user reopens the
integrated Excel workbook or invokes an action that interacts with the Fusion web application. In addition to configuring the page definition file, configure the functionality in an integrated Excel workbook so that pending changes are not lost if the end user logs off from the Fusion web application or a session expires before changes are committed to the Fusion web application. For example, you configure the worksheet Startup event to invoke a CreateInsert action binding and a worksheet DownSync action. You also configure an ADF Button component labeled Save to invoke the worksheet UpSync action and the Commit action binding. If the end user's session ends, no record is saved even if the end user clicks the Save button after the Fusion web application assigns a new session. To prevent this scenario occurring, it is better to invoke the CreateInsert action binding from the ADF Button component labeled Save. Another example is the behavior of the ADF Table component's DownloadForInsert action. If you create a custom method in the Fusion web application that creates temporary records to support the invocation by the ADF Table component of the DownloadForInsert action, make sure to remove these temporary records after successful invocation of the DownloadForInsert action. For more information about the use of the DownloadForInsert action, see Section 7.5, "Configuring a Worksheet to Download Data as Pending Insert Rows in an ADF Table component."
15.2.1 How to Configure an Integrated Excel Workbook to Restore Server Data Context
You specify the attribute bindings that you want to cache in an integrated Excel workbook between sessions as values for the worksheet's ServerContext group of properties. This group of properties also enables you to specify the action binding that uses the cached attribute binding data to restore server-side context when a Fusion web application assigns a new session to the integrated Excel workbook. Before you can specify values for the ServerContext group of properties, the page definition file that is associated with the worksheet must expose the attribute bindings and action bindings for which you want to restore server context. For information about adding attribute bindings and action bindings to a page definition file, see Section 4.3, "Working with Page Definition Files for an Integrated Excel Workbook." For information about the ServerContext group of properties, see the entry for ServerContext in Table A19. Before you begin: It may be helpful to have an understanding of how to restore server data context. For more information, see Section 15.2, "Restore Server Data Context Between Sessions." You may also find it helpful to understand functionality that can be added using other ADF Desktop Integration features. For more information, see Section 15.1.2, "Additional Functionality for Disconnected Workbooks." To configure an integrated Excel workbook to restore server data context: 1. Open the integrated Excel workbook.
2. 3.
In the Workbook group of the Oracle ADF tab, click Worksheet Properties. In the Edit Worksheet Properties dialog, configure values for the ServerContext group of properties as described by Table 151.
Using an Integrated Excel Workbook Across Multiple Web Sessions and in Disconnected Mode 15-3
Table 151
ServerContext Properties to Restore Server Data Context Enter or select this value... Add an element to the collection of CacheDataContexts. Configure the element you add as follows:
RestoreDataContextActionID Specify the action binding (for example, the Execute action binding) that connects to the Fusion web application to restore the data specified by CachedServerContexts.
CachedServerContexts An array that identifies the attribute binding values to cache and set before the action binding specified by RestoreDataContextActionID is invoked. Each element in the array (CachedServerContext) supports the CachedAttributeID and RestoredAttributeID properties.
For more information about the CacheDataContexts property and its subproperties, see Section A19, " Worksheet Properties." IDAttributeID Specify the attribute binding that uniquely identifies the row displayed in the current worksheet. At runtime, the value that this property references is used to determine if the server data context has been correctly restored. For more information about this property and its subproperties, see Section A19, " Worksheet Properties."
If your integrated Excel workbook uses parameters and you have deployed it by downloading it from your Fusion web application, see Section 14.5.3, "How to Configure Parameters Properties in the Integrated Excel Workbook."
4.
Click OK.
Note:
For integrated Excel workbooks that use Parameters and <invokeAction> executable, you may not need to configure RestoreDataContextActionID and CachedServerContexts, if Parameters and <invokeAction> can restore server data context when a new session is created.
15.2.2 What Happens at Runtime: How the Integrated Excel Workbook Restores Server Data Context
During the session that is assigned the initial session (for example, session ID 1), the worksheet caches data using the ServerContext group of properties. In a later session with a different session ID (for example, session ID 2), where the ADF Table component's Upload action is invoked, the data cached in the ServerContext group of properties is sent to the Fusion web application.
Table 152
Types of Data an Integrated Excel Workbook Caches Is cached when... An integrated Excel worksheet bound to a page definition file is activated and no cache of the page definition file's configuration exists. And refreshed when... The page definition configuration is not refreshed unless you download a new copy of the integrated Excel workbook or invoke the workbook actions ClearAllData and EditOptions described in Table A17. The values of the list items hosted by the Fusion web application differ from those cached by the integrated Excel workbook. The cached list items are refreshed only once per workbook session and only if a workbook session exists. Invoking the workbook actions ClearAllData and EditOptions described in Table A17 also clears cached list items.
This type of data... Page definition configuration that is not runtime specific such as control binding types, IDs, and labels.
The ADF List of Values component first downloads the list items from the Fusion web application.
The integrated Excel workbook is first initialized. A workbook is initialized when it is opened for the first time after conversion, or after ClearAllData is invoked.
The cache of resource bundle strings is not refreshed unless you download a new copy of the integrated Excel workbook or invoke the workbook actions ClearAllData and EditOptions described in Table A17.
Section 6.6, "Inserting an ADF List of Values Component" Section 7.14, "Creating a List of Values in an ADF Table Component Column" Section 8.8, "Creating Dependent Lists of Values in an Integrated Excel Workbook"
ADF Desktop Integration caches up to two hundred and fifty values for each component. If a component references a list of values with more than two hundred and fifty values, ADF Desktop Integration caches the first two hundred and fifty values and writes a warning message to the client-side log file for subsequent values. Consider configuring your integrated Excel workbook to invoke a pick dialog from a page in your Fusion web application where a list of values references more than two hundred and fifty values. For more information about client-side log files, see Section C.3, "Generating Log Files for an Integrated Excel Workbook." For more information about invoking a pick dialog from a Fusion web application page, see
Using an Integrated Excel Workbook Across Multiple Web Sessions and in Disconnected Mode 15-5
Section 8.4, "Displaying Web Pages from a Fusion Web Application" and Section 8.5, "Adding a Custom Popup Picker Dialog to an ADF Table Column." Cached list of values in an integrated Excel workbook get refreshed once per workbook session. This refresh occurs after the user reestablishes a web session with the Fusion web application and if the values referenced by the Fusion web application have changed since the integrated Excel workbook last cached the list of values. The upload of a selected value from a list of values causes the upload to fail if the selected value no longer exists in the Fusion web application. This may occur if, for example, one end user deletes the value in the Fusion web application while another end user modifies the selected value in the cached list of values of an integrated Excel workbook and attempts to upload the modified value to the Fusion web application. For more information about handling data conflict, see Section 12.7, "Handling Data Conflicts When Uploading Data from a Workbook." Note that if you change the Fusion web application configuration after you have deployed the Fusion web application and the end users have started using the published integrated Excel workbooks, you must inform the end users to download a fresh copy of the integrated Excel workbook, or run the ClearAllData command. For more information about the ClearAllData action, see Table A17 The changes in your Fusion web application might include changing the definitions of the list bindings associated with the ADF List of Values and TreeNodeList subcomponents exposed in the worksheet. Changing list binding configuration can cause unexpected exceptions in workbooks that have been downloaded and run prior to the change.
A
A
This appendix lists and describes the properties of ADF Desktop Integration components. It also describes the actions that certain components (such as ADF Input Text, ADF Output Text, ADF List of Values, ADF Button, ADF Table, Workbook, and Worksheet) expose. This appendix includes the following sections:
Section A.1, "Frequently Used Properties in the ADF Desktop Integration" Section A.2, "ADF Input Text Component Properties" Section A.3, "ADF Output Text Component Properties" Section A.4, "ADF Label Component Properties" Section A.5, "ADF List of Values Component Properties" Section A.6, "TreeNodeList Subcomponent Properties" Section A.7, "ModelDrivenColumnComponent Subcomponent Properties" Section A.8, "ADF Button Component Properties" Section A.9, "ADF Table Component Properties and Actions" Section A.10, "ADF Read-only Table Component Properties and Actions" Section A.11, "Action Set Properties" Section A.12, "Workbook Actions and Properties" Section A.13, "Worksheet Actions and Properties"
A-1
Frequently Used Properties in ADF Desktop Integration Type EL N String N Description For information about action sets, see Section A.11, "Action Set Properties." Use this field to enter a comment about the component's use in the worksheet. Comments you enter have no effect on the behavior of the workbook. They are the equivalent of code comments. ADF Desktop Integration generates this string to uniquely identify each instance of an ADF component in an integrated Excel workbook. Specify an EL expression that is evaluated at runtime. For information about EL expressions in ADF Desktop Integration, see Appendix B, "ADF Desktop Integration EL Expressions." For information about using labels, see Section 9.4, "Using Labels in an Integrated Excel Workbook." This property defines the upper-left corner of the Oracle ADF component in the integrated Excel workbook.
Annotation
ComponentID
String
Label
String
Position
Table A1 (Cont.) Frequently Used Properties in ADF Desktop Integration Name ReadOnly Type Boolean EL Y Description Set this property to TRUE so that ADF Desktop Integration ignores changes a user makes to a cell that references a component which uses this property. This property is independent of Excel's workbook and worksheet protection functionality. Setting ReadOnly to TRUE does not prevent a user from modifying a cell. When TRUE, the behavior for cells that reference Oracle ADF components is as follows:
ADF Desktop Integration overwrites changes without warning when a worksheet is refreshed. No changes are sent to the Fusion web application when the integrated Excel workbook is synchronized with the Fusion web application.
To avoid end user confusion, apply styles to the cells where you set ReadOnly to TRUE that provide a visual clue to users that they cannot modify the cell's contents. For information about applying styles, see Section 9.2, "Working with Styles." You can also use the Worksheet Protection feature of ADF Desktop Integration to prevent editing of locked cells at runtime. For more information, see Section 9.7, "Using Worksheet Protection." Setting the ReadOnly property to True for an ADF List of Values component, a TreeNodeList subcomponent, or a ModelDrivenColumn component which renders a list binding may confuse end users. To avoid any confusion, consider using an ADF Output Text component or subcomponent. StyleName String Y Specifies the style in the current Excel workbook to apply when the Oracle ADF component is rendered. For more information, see Section 9.2, "Working with Styles." This property references an EL expression that is evaluated after the invocation of the ADF Table component's RowDownSync action or a worksheet's DownSync action. The resulting value is typically the primary value seen in the selected component.
Value
Varies
Many label-type properties are optional and default to empty. At runtime, if the value of the property is empty, ADF Desktop Integration provides a default, localized value. If you want the value of the property to appear as empty, set its value to a single space character, or provide an EL expression that evaluates to an empty string.
A-3
Table A2 Name
ADF Input Text Component Properties Description For information about this property, see Table A1. For information about this property, see Table A1.
Annotation ComponentID
InputText.DoubleClickAction Specifies the action set invoked when a user double-clicks the cell. For Set information about action sets, see Section A.11, "Action Set Properties." InputText.ReadOnly InputText.Value Position StyleName For information about this property, see Table A1. For information about this property, see Table A1. For information about this property, see Table A1. For information about this property, see Table A1.
ReadOnly
A-5
ReadOnly Value
ClickActionSet Specify the action set to invoke when a user clicks the button. For information about action sets, see Section A.11, "Action Set Properties." ComponentID Label For information about this property, see Table A1. For information about this property, see Table A1.
LowerRightCorn This property is an Excel cell reference. Used with Position, it specifies the area that the er button occupies on the Excel worksheet. Position For information about this property, see Table A1.
Table A9 Name
ADF Table Component Properties Type EL Description For information about this property, see Table A1. This group of properties enables you to configure batch options for the ADF Table component. For more information about how you use these properties, see Section 7.11, "Batch Processing in an ADF Table Component." Integer N Specifies how many rows to process before an ADF Table component action (Upload or DeleteFlaggedRows) invokes CommitBatchActionID. Any value other than a positive integer results in all rows being processed in a single batch. The default value is 100 rows. A value for this property is required.
Annotation BatchOptions
BatchOptions.BatchSize
Specify an action binding to invoke when the number of rows specified by BatchSize have been processed. The action binding is expected to be a commit-type action. Set this property to TRUE to process rows in batches where each batch contains the number of rows specified by BatchSize. If set to FALSE, all rows are processed in a single batch. Specify an action binding to invoke at the beginning of each batch. For example, this property might be used for an operation like "start transaction", if required by a particular database. A value for this property is optional.
BatchOptions.LimitBatchSize
Boolean
Columns
An array of columns. For information about the properties that each column in the array supports, see Section A.9.2, "ADF Table Component Column Properties." For information about this property, see Table A1. For information about this property, see Table A1. This group of properties allows you specify which actions are enabled and can be invoked. Action binding N Specify an action binding to invoke for each row flagged for deletion. A value for this property is optional.
RowActions.DeleteRowEnabled
Boolean
Set to TRUE to allow a user to delete existing rows. FALSE is the default value. A value for this property is required.
RowActions.FailureActionID
Action binding
Specify an action binding to invoke if failures occur during the processing of rows. A value for this property is optional.
Specify an action binding to invoke for each row inserted using the ADF Table component Upload action. The action binding is invoked after the attributes are set. Use of this property is suitable with a custom action where a variable iterator is employed along with the main iterator. A value for this property is optional.
A-7
Table A9 (Cont.) ADF Table Component Properties Name Type EL N Description Specify an action binding to invoke for each row inserted using the Upload component action. The action binding specified is invoked before the attributes are set. A value for this property is optional. RowActions.InsertRowEnabled Boolean N Set to TRUE to allow the end user insert new rows in the ADF Table component. FALSE is the default value. If you set this property to TRUE, you must specify values for one or both of the following properties:
RowActions.InsertAfterRowActionID RowActions.InsertBeforeRowActionID
Which property (InsertAfterRowActionID or InsertBeforeRowActionID) you specify a value for depends on how your Fusion web application creates new rows. Typically, a Fusion web application uses the CreateInsert action binding to create and insert a new row. In this scenario, you specify the CreateInsert action binding as the value for InsertBeforeRowActionID. For more information about inserting rows in an ADF Table component, see Section 7.7, "Configuring an ADF Table Component to Insert Data." RowActions.InsertRowsAfterUplo Boolean adEnabled N Set to TRUE to allow the end user to reinsert changed rows regardless of whether they have been previously uploaded. FALSE is the default value. The property is ignored if InsertRowEnabled is set to FALSE. RowActions.UpdateRowActionID Action binding N Specify an action binding to invoke for each row updated. A value for this property is optional. RowActions.UpdateRowEnabled Boolean N Set to TRUE to allow a user update an existing row. TRUE is the default value. A value for this property is required. RowData Set values for the CachedAttributes property when you want to cache data in an integrated Excel workbook across multiple sessions with the Fusion web application. Set a value for the ChangeIndicatorAttributeID property to determine whether a row has been modified by another user since you downloaded it from the Fusion web application.
Table A9 (Cont.) ADF Table Component Properties Name RowData.CachedAttributes Type Array EL N Description Specify values for the properties in this array to determine the attributes for which data is cached. Each CachedTreeAttribute element in this array supports the following properties:
Value Select the tree binding attribute for which data is to be cached.
Annotation For more information about this property, see Table A1.
Do not configure a component (for example, an ADF Table component's column or an ADF Input Text component) so the end user can view or edit an attribute binding that you have also specified for an element in the RowData.CachedAttributes array. The RowData.CachedAttributes array caches the values retrieved by the worksheet DownSync action. The worksheet UpSync action sends the values cached by the RowData.CachedAttributes array to the Fusion web application. This may override edits the end user makes to an attribute binding exposed through a component in the worksheet. For information about using the RowData.CachedAttributes array to cache data in an ADF Table component, see Section 8.5, "Adding a Custom Popup Picker Dialog to an ADF Table Column." RowData.ChangeIndicatorAttribu Attribute teID Binding Y Specify an EL expression that evaluates to a row-specific tree attribute binding value. The attribute value is used to determine if a row has been modified by another user since the row was last downloaded to your integrated Excel workbook. For more information, see Section 12.7, "Handling Data Conflicts When Uploading Data from a Workbook." RowLimit This group of properties allows you configure the number of rows that the ADF Table component or ADF Read-only Table component download and display. For more information, see Section 7.18, "Limiting the Number of Rows Your Table-Type Component Downloads." RowLimit.Enabled Boolean N Set to TRUE to limit the number of rows downloaded to the value specified by RowLimit.MaxRows. TRUE is the default value. A value for this property is required.
A-9
Table A9 (Cont.) ADF Table Component Properties Name RowLimit.MaxRows Type Integer EL Y Description Specify an EL expression that evaluates to the maximum number of rows to download. The component evaluates the EL expression when it invokes its Download action. The default value is 500. If MaxRows is not a positive integer, the component attempts to download as many rows as possible. An invalid expression such as "ABC" is interpreted as -1 (negative integer). As a result, the component attempts to download as many rows as possible. Note that setting the value of MaxRows to 0 results in a message where the user is asked if they want to download the first 0 rows. To avoid this, set MaxRows to a positive integer other than 0.
Table A9 (Cont.) ADF Table Component Properties Name RowLimit.WarningMessage Type String EL Y Description (Optional) Write an EL expression to generate a message to display to the end user if the number of rows available to download exceeds the number specified by RowLimit.MaxRows. This expression is evaluated each time the Table's Download action is invoked. The maximum number of rows that a Excel 2007, or a higher version, worksheet can contain is approximately 1 million. If this property is left blank, ADF Desktop Integration displays a message similar to "Too many rows available. Do you want to download the first {0} rows?" that is translated for the current culture settings. You can specify a string key from a custom resource bundle to use, instead of the default value. If desired, you may supply a custom message to replace the default one. Any custom message must contain {0}. {0} will be replaced by the MaxRows value. For more information about resource bundles, see Section 10.2, "Using Resource Bundles in an Integrated Excel Workbook." TreeID Binding N Specify a tree binding from the current worksheet's page definition file. You must specify a value for this property so that row downloads and uploads function properly. For more information about the page definition requirements for an integrated Excel workbook, see Table 41. Specify an EL expression that evaluates to a unique row-specific tree attribute binding value. The value of this attribute is cached in the integrated Excel workbook during the ADF Table component's Download action. ADF Desktop Integration uses this value to ensure that the tree binding's iterator is positioned correctly before setting or getting data for a given ADF Table component row. Note that this value is required only when the underlying tree binding iterator does not expose a rowKey. This value is optional when:
UniqueAttribute
Attribute binding
The tree binding iterator exposes a rowKey, in which case the rowKey value is used for positioning OR
The ADF Table component is configured to be insert-only (RowActions.InsertRowEnabled is set to True and RowActions.UpdateRowEnabled is set False)
ADF Table Component Column Properties Type EL Description For information about this property, see Table A1. String Boolean Y N Write an EL expression that resolves to an Excel style name that is applied to each cell in the column. Set to True to make a column dynamic. False is the default value. For more information about dynamic columns, see Section 7.16, "Adding a Dynamic Column to Your ADF Table Component." Write an EL expression that, when evaluated at runtime, displays a label in the column header. Write an EL expression that resolves to an Excel style name that is applied to each cell in the column header. Assign a name to the column to identify it and its purpose. The value that you assign for this property has no functional impact. However, you must specify a value and the value that you specify must be unique within the list of columns. It serves to help you keep track of columns in the ADF Table component. The following IDs are reserved to the three default columns in the ADF Table component:
CellStyleName DynamicColumn
HeaderLabel HeaderStyleName ID
Y Y N
For more information about these columns, see Section 7.12, "Special Columns in the ADF Table Component." InsertComponent ADF component N Specifies the properties of the component that represents the binding for insert operations. This component can be one of the following:
InputText component For information about the properties that this component supports, see Section A.2, "ADF Input Text Component Properties."
OutputText component For information about the properties that this component supports, see Section A.3, "ADF Output Text Component Properties."
TreeNodeList component For information about the properties that this component supports, see Section A.6, "TreeNodeList Subcomponent Properties."
ModelDrivenColumnComponent For information about the properties that this component supports, see Section A.7, "ModelDrivenColumnComponent Subcomponent Properties."
When InsertUsesUpdate is set to True, the ADF Table component ignores the value of the InsertComponent property.
Table A10 (Cont.) ADF Table Component Column Properties Name InsertUsesUpdate Type Boolean EL N Description Set to True if insert and update operations use the same component type. When True, the ADF Table component ignores the values of the InsertComponent property and reads the value of the UpdateComponent property. The default value is True. UpdateComponent ADF component N Specifies the properties of the component that represents the binding for update and download operations. This component can be one of the following:
InputText component For information about the properties that this component supports, see Section A.2, "ADF Input Text Component Properties."
OutputText component For information about the properties that this component supports, see Section A.3, "ADF Output Text Component Properties."
TreeNodeList component For information about the properties that this component supports, see Section A.6, "TreeNodeList Subcomponent Properties."
ModelDrivenColumnComponent For information about the properties that this component supports, see Section A.7, "ModelDrivenColumnComponent Subcomponent Properties."
Visible
Boolean
Write an EL expression that resolves to True or False. If True, the column appears in the ADF Table component. If False, the column does not appear. True is the default value. If you make a column dynamic, the ADF Table component ignores the value of the Visible property. For more information about dynamic columns, see Section 7.16, "Adding a Dynamic Column to Your ADF Table Component."
DeleteFlaggedRows
Table A11 (Cont.) ADF Table Component Actions Component Action DisplayTableErrors Description Displays a detailed list of errors in a message dialog for the ADF Table component if any errors are available. Do not invoke this action from a column's action set in an ADF Table component. Instead configure an action set for an ADF Button, ADF Output Text component, or worksheet ribbon button to invoke this action. Download the rows corresponding to the current state of TreeID. For information about TreeID, see Section A.9.1, "ADF Table Component Properties." Downloads the flagged rows from the tree binding specified by TreeID. For information about TreeID, see Table A9. This action applies to the downloaded rows only, and inserted rows are ignored. DownloadForInsert FlagAllRows This action is obsolete. For more information, see Section 7.4, "Configuring Oracle ADF Component to Download Data to an ADF Table Component." Sets the flag for all rows. Invoke this action to set a flag character in all rows of the _ADF_FlagColumn column. The flag character has the following properties: Character Code 25CF, Unicode(hex) It appears as a solid circle. For more information about the _ADF_FlagColumn column, see Section 7.11.2, "Row Flagging in an ADF Table Component" and Section 7.12, "Special Columns in the ADF Table Component." Initialize This action performs the following actions:
Download
DownloadFlaggedRows
Removes all rows of data from the ADF Table component Clears the values of cached attributes from rows in the ADF Table component Creates the placeholder row Recalculates how many dynamic columns to render in the ADF Table component Redraws column headers
If the ADF Table component contains pending changes that have not been saved in the integrated Excel workbook, a dialog appears to the end user that allows cancellation of invocation of this action. MarkAllRowsChanged MarkAllRowsUnchanged RowDownSync Specify this component action to mark all rows in the table as changed in _ ADF_ChangeColumn. Specify this component action to clear all flags from the _ADF_ ChangedColumn column. Synchronizes data from the row in the ADF Table component's iterator in the Fusion web application that corresponds to the current worksheet row to the worksheet. As this action acts upon the current worksheet row, only a DoubleClickActionSet associated with a column in the ADF Table component should invoke this action. The ADF Table component does not evaluate or apply the value of a column's Visible property when invoking RowDownSync. The ADF Table component evaluates and applies the value of a column's CellStyleName property when invoking RowDownSync. For more information about column properties, see Section A.9.2, "ADF Table Component Column Properties."
Table A11 (Cont.) ADF Table Component Actions Component Action RowUpSync Description Synchronizes any pending changes in the current worksheet row that the ADF Table component references to the Fusion web application. RowUpSync acts upon the current worksheet row so only a DoubleClickActionSet associated with a column in the ADF Table component should invoke this action. The DoubleClickActionSet that invokes RowUpSync also changes the position of the ADF Table component's iterator on the Fusion web application to the current worksheet row (assuming it exists in the Fusion web application). Removes flags from cells in the _ADF_FlagColumn column. For more information about the _ADF_FlagColumn, see Section 7.11.2, "Row Flagging in an ADF Table Component" and Section 7.12, "Special Columns in the ADF Table Component." Upload Uploads pending changes to the Fusion web application. Commits successful rows even if row failures occur. For more information, see Section 7.8, "Configuring an ADF Component to Upload Changes from an ADF Table Component." For more information about resolving data conflict between the Excel workbook and the Fusion web application, see Section 12.7, "Handling Data Conflicts When Uploading Data from a Workbook". UploadAllOrNothing Uploads pending changes to the Fusion web application. Commits successful rows only if none of the rows fail. For more information about Upload action, see Section 7.8, "Configuring an ADF Component to Upload Changes from an ADF Table Component." For more information about UploadAllOrNothing action, see Section 7.9, "Configuring an ADF Table Component to Upload Changes Using UploadAllOrNothing Action."
UnflagAllRows
Table A13 lists alphabetically the properties that a column in the ReadOnlyColumn array can use.
ADF Read-only Table Component Column Properties Type EL Description For information about this property, see Table A1. String String String String Y Y Y N Write an EL expression that resolves to an Excel style name that is applied to each cell in the column. Write an EL expression that resolves to a label for the column header. Write an EL expression that resolves to an Excel style name that is applied to each cell in the column header. Assign a name to the column to identify it and its purpose. The value that you assign for this property has no functional impact. However, you must specify a value and the value that you specify must be unique within the list of columns. It serves to help you keep track of columns in the ADF Read-only Table component. For information about the properties that this component supports, see Section A.3, "ADF Output Text Component Properties."
OutputText
ADF Component
Table A14 (Cont.) Action Set Properties Name Actions Type Array EL Description N Specifies an ordered array of actions. An action can be one of the following:
ADFmAction Invokes an action binding or method action binding in the underlying page definition file. The ADFmAction.ActionID property identifies the action binding or method action binding to invoke. For information about page definition files, see Section 4.3, "Working with Page Definition Files for an Integrated Excel Workbook."
ComponentAction Invokes an action that a component on the worksheet exposes. ComponentAction.ComponentID identifies the component that exposes the action while ComponentAction.Method identifies the action to invoke. The ADF Table and ADF Read-only Table components are the only components in ADF Desktop Integration that expose actions. For information about these actions, see Section A.9, "ADF Table Component Properties and Actions" and Section A.10, "ADF Read-only Table Component Properties and Actions." For information about invoking component actions, see Section 8.2.2, "How to Invoke Component Actions in an Action Set."
WorksheetMethod Invokes a worksheet action. For information about worksheet actions, see Section A.13, "Worksheet Actions and Properties."
Confirmation Invokes a confirmation dialog. For more information about the properties that this action uses, see Section A.11.1, "Confirmation Action Properties."
Dialog Invokes a web page in a popup dialog or Excel's task pane. For more information, see Section 8.4, "Displaying Web Pages from a Fusion Web Application."
Alert
This group of properties determines if and how an alert-style dialog appears to the user to indicate that the requested action is complete. The dialog that appears contains one button that allows the user to acknowledge the message and dismiss the dialog. For information about how to display an alert message, see Section 8.2.8, "How to Provide an Alert After the Invocation of an Action Set." Many properties in this group make use of EL expressions to retrieve string values from resource bundles. For more information about using EL expressions, see Section 10.2, "Using Resource Bundles in an Integrated Excel Workbook."
Alert.Enabled
Boolea N n
Set to TRUE to display an alert message to end users that notifies them when an action set operation completes successfully or includes one or more failures. For more information, see Section 8.2.8, "How to Provide an Alert After the Invocation of an Action Set."
Alert.FailureMessage
String
Specify an EL expression that evaluates to a message to appear in the dialog if errors occur during execution of the action set.
Table A14 (Cont.) Action Set Properties Name Alert.OKButtonLabel Alert.SuccessMessage Type String String EL Description Y Y Specify an EL expression that evaluates to a message to appear in the OK button of the dialog. Specify an EL expression that evaluates to a message to appear in the dialog if no errors occur during the execution of the action set. Specify an EL expression that evaluates to a message to appear in the title area of the dialog. For information about Annotation, see Table A1. This group of properties determines if and how a status message appears during the execution of an action set. For information about how to display a status message, see Section 8.2.5, "How to Display a Status Message While an Action Set Executes." Many properties in this group make use of EL expressions that reference string keys defined in resource bundles. For more information, see Section 10.2, "Using Resource Bundles in an Integrated Excel Workbook." Status.Enabled Status.Message Status.Title Status.Mode Boolea N n String String String Y Y N If TRUE (default), a status window appears during the execution of the action set. If FALSE, no status window appears. Specify an EL expression to evaluate and display in the status window while the action set executes. Specify an EL expression to evaluate and display in the title area of the status window while the action set executes. Choose the visual appearance of progress bars. The valid values are Automatic, BothBarsAlways, MainBarOnly, DetailBarOnly, and MainMessageOnly. Specify an optional EL expression or literal value that evaluates to a status message to appear as the associated action progresses.
String
Status.DetailStatusMessage String
ShareFrame Boolean
Target
List
Popup to render the web page in a modal dialog within an embedded web browser. TaskPane to render the web page in runtime task pane.
Title
String
Y N
Write an EL expression that resolves to the title of the Dialog at runtime or write a literal string. Specify the initial size in pixels of the dialog that appears to the user. Valid values range from 0 to 2147483647. Values will be revised upwards or downwards as appropriate at runtime if the specified values are too large or too small. The default value for Height is 625 and 600 for Width.
WindowSize Integer
Workbook Actions Description When invoked, this action creates a new session between the integrated Excel workbook and the Fusion web application. If invoked when a session has already been established, it first invokes the Logout action internally to free that session. For a workbook running against a web application that is enforcing authentication, the Login action prompts the end user to provide valid user credentials.
Logout
When invoked, ADF Desktop Integration sends a request to the Fusion web application to invalidate the session between the integrated Excel workbook and the Fusion web application. After invoking this action, the end user must be authenticated the next time the Excel workbook accesses the Fusion web application. When invoked, this action clears all data entered by the user from cells that reference Oracle ADF bindings. Tables, such as those created by the ADF Table and ADF Read-only Table components, will be truncated so that they only display header rows with labels cleared. Values in cells that reference the Input Text or Output Text components are cleared. Column headers and labels are cleared as well. References to all resource bundles that the integrated Excel workbook uses are cleared. Worksheets that do not contain bindings or reference a page definition file remain unchanged. A dialog prompts the end user to confirm invocation of this action. Once the end user confirms invocation, ADF Desktop Integration executes the following events after invocation of the action:
ClearAllData
Invokes the integrated Excel workbook's Logout action Terminates the runtime session and clears all data from the integrated Excel workbook and all caches Reinitializes the integrated Excel workbook and invokes the workbook's Login action
Invocation of the ClearAllData action does not change data hosted by the Fusion web application. One or more of the following actions must be invoked to change data hosted by the Fusion web application:
A worksheet's UpSync action This action synchronizes all data referenced by non-table type components. For more information, see Section A.13, "Worksheet Actions and Properties."
An ADF Table component's RowUpSync action can be used to synchronize any pending changes in a row to the Fusion web application. The ADF Table component's DeleteFlaggedRows action can be invoked to delete flagged rows. For more information about ADF Table component actions, see Section A.9.3, "ADF Table Component Actions."
EditOptions
When invoked, this action launches a dialog that shows the current value of the WebAppRoot property and allows the end user to enter a new value. If the end user chooses to change the value of WebAppRoot, a confirmation dialog appears after the end user clicks OK. Once the change is confirmed, the following events occur:
Workbook ClearAllData action is invoked Workbook Logout action is invoked All data referenced by bindings in the workbook is removed References to WebAppRoot are updated in the Excel workbook's configuration Workbook Login action is invoked to authenticate the user with the Fusion web application that is specified as the value for WebAppRoot The ClearAllData workbook action clears all resource bundles referenced by the integrated Excel workbook. After WebAppRoot is changed, the integrated Excel workbook attempts to retrieve resource bundles from the Fusion web application as part of the reinitialization process. This request to the Fusion web application triggers the authentication process.
ViewAboutDialog When invoked, this action launches a dialog called About that displays information defined in the BrandingItems workbook property and other information such as the versions of supporting software.
Table A18 lists alphabetically the ADF Desktop Integration properties that an Excel workbook can use.
Table A18 Name ApplicationHomeFolder Workbook Properties Type String EL N Description Specify the absolute path to the directory that is the root for the JDeveloper application workspace (.jws) where you developed the desktop integration project. For example, the value of this property in a workbook integrated with the Summit sample application for ADF Desktop Integration could be something similar to the following: D:\Oracle\Applications\Summit_ADFdi ADF Desktop Integration prompts you to specify a value for this property the first time that you open an integrated Excel workbook. For more information, see Section 4.2.2, "How to Configure a New Integrated Excel Workbook." BrandingItems Array N An array of name-value pairs that resolve to resource bundle references (for example, #{res['myAppName']}) or a literal string. Each pair in the array consists of a name and a value. Each name and value can reference a literal string or an EL expression. For information about branding your integrated Excel workbook, see Section 9.6, "Branding Your Integrated Excel Workbook." Login.WindowSize Integer N Specify the initial size in pixels of the login dialog that appears to the user. Valid values range from 0 to screen width or height. Values will be revised upwards or downwards as appropriate at runtime if the specified values are too large or too small. The default value for Height is 625 and Width is 600. An array of workbook initialization parameters that you configure to pass the parameters from a page in a Fusion web application to an integrated Excel workbook. You can define multiple workbook initialization parameters in the Fusion web application's page. Each workbook initialization parameter (parameter that references a URL argument) that you define in a page must be specified in a Parameter property of this array, otherwise it is ignored. Each element in the array supports the following properties:
Parameters
Array
Annotation For more information about this property, see Table A1.
Parameter You specify the name of the workbook initialization parameter you defined in the page of the Fusion web application from which the end user downloads the integrated Excel workbook.
For information about using this property, see Section 14.5, "Passing Parameter Values from a Fusion Web Application Page to a Workbook."
Table A18 (Cont.) Workbook Properties Name Project Type String EL N Description Specify the name of a JDeveloper project in the current JDeveloper workspace. ADF Desktop Integration attempts to load the .jpr file that corresponds to the project that you specify. An error appears if the .jpr file is not available or is not in the expected format. When you open an integrated Excel workbook for the first time in design mode, ADF Desktop Integration searches for a .jpr file in the parent folder hierarchy. If it finds a .jpr file, it sets the value of Project to the name of the project that corresponds to the .jpr file. ADF Desktop Integration loads the names of the available projects from the application_name.jws file specified by ApplicationHomeFolder. RemoteServletPath String N Specify the path to the ADF Desktop Integration remote servlet. This path must be relative to the value specified for WebAppRoot. Note that the value you specify for RemoteServletPath must match the value that is specified in the web application's deployment descriptor file (web.xml). The default value for this property is: /adfdiRemoteServlet Resources Array N Specifies an array of resource bundles to register with the workbook. Each element in the array supports the following properties:
Alias Specify a string value that is unique within Workbook.Resources. EL expressions use this string to reference the resource bundle.
Annotation For more information about this property, see Table A1.
Class Specify a fully qualified class name, but do not include the file extension. The class name that you specify is expected to be a Java resource bundle class that the Fusion web application you integrate your workbook with uses. For example, the EditCustomers-DT.xlsx workbook in the Summit sample application for ADF Desktop Integration references the following resource bundle: oracle.summitdi.resources.UIStrings
For more information, see Section 10.2, "Using Resource Bundles in an Integrated Excel Workbook." Runtime Ribbon Tab This group of properties defines whether and how a Ribbon tab appears in Excel at runtime. The following entries in this table describe the properties in the Runtime Ribbon Tab group. For more information about Ribbon tab and its commands, see Section 8.3, "Configuring the Runtime Ribbon Tab." For information about this property, see Section A.1, "Frequently Used Properties in the ADF Desktop Integration." If TRUE,the Ribbon tab appears at runtime. The Ribbon tab does not appear if you set Enabled to FALSE. TRUE is the default value.
String
Table A18 (Cont.) Workbook Properties Name Runtime Ribbon Tab.Title Type String EL Y Description Specify an EL expression that evaluates to the title that appears for the Ribbon tab in the title area. Excel imposes a maximum limit of 1024 characters for Ribbon tab titles. Ensure that the runtime value of the EL expression you specify does not exceed 1024 characters as ADF Desktop Integration truncates the value so that Excel does not generate an error message. If you choose to assign a key tip character using the & character, consider avoiding the letter K for the Runtime Ribbon Tab.Title. Excel does not allow the letter K to be used here when the workbook is running in the ar_SA culture. Runtime Ribbon Tab.Workbook Commands Array N Each element in this array corresponds to a workbook command at runtime. Each element in the array uses the following properties:
Annotation For more information about this property, see Table A1.
Label For more information about this property, see Table A1. If you want the & character to appear in the command label, you must specify &&. Excel interprets a single & character as a special character, and assigns the next character after & as the keyboard accelerator for the workbook command at runtime.
Method Specify the workbook action that the workbook ribbon button invokes. For more information about workbook actions, see Table A17.
WebAppRoot WebPagesFolder
String String
N N
A fully qualified URL to the Fusion web application's root. Specify the path to the directory that contains the web pages that you intend to use with your integrated Excel workbooks. The value that you specify for the path most be relative to the value of ApplicationHomeFolder. A unique identifier for the integrated Excel workbook. ADF Desktop Integration generates the unique identifier when you open the workbook for the first time in design mode. The value cannot be modified. However, ADF Desktop Integration can generate a new value if you use the Reset WorkbookID link in the Edit Workbook Properties dialog. The value of this property is used during tamper check, as described in Section 11.3, "Checking the Integrity of an Integrated Excel Workbook's Metadata."
WorkbookID
String
UpSync Synchronizes any pending changes from the ADF Input Text and ADF List of Values components in the worksheet to the Fusion web application.
DownSync
Downloads any changes from the Fusion web application to the ADF Input Text, ADF Output Text, and ADF List of Values components in the worksheet.
DisplayWorksheetErrors Displays a detailed list of errors in a message dialog for the integrated Excel worksheet if any errors are available. Invoke this action in an action set that is invoked by an ADF component (other than the ADF Table-type components) or a worksheet ribbon button.
When you configure an ADF Button component to invoke an action binding or method action binding, the action set to invoke when a user clicks the ADF Button component at runtime is populated as follows by default:
1. 2. 3.
UpSync Action or method action binding that you specify for the ADF Button component DownSync
If the first action that you invoke on a worksheet with an empty form is the UpSync worksheet action, you may encounter errors. For this reason, ensure that the first action invoked is the DownSync worksheet action. You can configure the ADF Button component's action set or one of the worksheet events (Startup or Activate) described in Table A19 to invoke the DownSync worksheet action first. Table A19 describes the ADF Desktop Integration properties that an Excel worksheet can use.
Table A19 Name Annotation Events Worksheet Properties Type String Array EL Description N N For information about this property, see Table A1. Each element in this array specifies an action set to invoke if the associated worksheet event occurs. For information about action sets, see Section A.11, "Action Set Properties." For information about worksheet events, see the entry in this table for Events.n.Event. The following entries in this table prefaced by Events.n describe the properties that an element in this array supports where n refers to a specific element in the array. Events.n.ActionSet Events.n.InvokeOnceOnly ActionSe N t Boolean N For more information about the properties of action sets, see Section A.11, "Action Set Properties." The default value of this property is FALSE. When set to TRUE, the workbook stores information about whether the worksheet invoked the action set for this event and, if so, prevents the worksheet from invoking the action set a second time. Note that if the workbook is not saved, this information is lost. This means that the worksheet can invoke the event again the next time that the workbook opens. Events.n.Annotation String N For information about the annotation property, see Table A1.
Table A19 (Cont.) Worksheet Properties Name Events.n.Event Type List EL Description N The worksheet supports the following events that you can configure to invoke an action set:
Startup Excel workbook opens and the worksheet is activated for the first time.
Deactivate User navigates away from the current worksheet or Shutdown event triggered.
Note that the worksheet events complete execution even if the action sets that they invoke fail. For more information about worksheet events and action sets, see Section 8.2.4, "How to Invoke an Action Set from a Worksheet Event." Protection.Mode List N The worksheet provides two options:
The default value for this property is Off. Protection.Password String N Specify a password to prevent end-users from turning off sheet protection at runtime. The maximum password length allowed by Excel is 255 characters. Specify one or more workbook actions that appear as commands at runtime. Each command is an element in the WorksheetMenuItem array. Entries in this array support the following properties:
Ribbon Commands
Array
For more information about the Annotation and Label properties, see Table A1. For more information about the SelectActionSet property, see Section A.11, "Action Set Properties." If you want the & character to appear in the command label, you must specify &&. Excel interprets a single & character as a special character, and assigns the next character after & as the keyboard accelerator for the worksheet command at runtime. Page Definition String N Specify the page definition file to associate with the worksheet. For information about page definition files, see Section 4.3, "Working with Page Definition Files for an Integrated Excel Workbook."
Table A19 (Cont.) Worksheet Properties Name Parameters Type Array EL Description N An array of worksheet parameters that you configure to pass the parameters from a workbook Parameters property to a worksheet in an integrated Excel workbook. Each element in the array supports the following properties:
Annotation For more information about this property, see Table A1.
Parameter Specify the ID of a parameter element that you added to the page definition file associated with the worksheet.
Value Write an EL expression that references the value of the Parameter property you specified for the workbook initialization parameter (workbook Parameters.Parameter property). The workbook Parameters.Parameter property supplies this value the first time that the page definition file associated with this worksheet is initialized.
For information about using this property, see Section 14.5, "Passing Parameter Values from a Fusion Web Application Page to a Workbook." RowData Set values for the CachedAttributes property when you want to cache data in an integrated Excel workbook across a multiple sessions with the Fusion web application. Set a value for the ChangeIndicatorAttributeID property to determine if a row has been modified by another user since you downloaded it from the Fusion web application. RowData.CachedAttributes Array N Specify values for the properties in this array to determine the attributes for which data is cached. Each CachedAttribute element in this array supports the following properties:
AttributeID This property references the attribute binding for which data is to be cached. Do not specify an attribute binding for AttributeID and as an editable field in a form (for example, in an ADF Input Text component) in the same worksheet.
Annotation For more information about this property, see Table A1.
For more information about clearing the values of cached attributes, see Section 7.19, "Clearing the Values of Cached Attributes in an ADF Table Component."
Table A19 (Cont.) Worksheet Properties Name Type EL Description N Specify the row-specific attribute of the tree binding used to determine if a row has been modified by another user since the row was last downloaded by to your integrated Excel workbook. For more information, see Section 12.7, "Handling Data Conflicts When Uploading Data from a Workbook." ServerContext This group of properties references the attribute bindings that uniquely identify the row displayed in the current worksheet so that you can reestablish server data context across multiple sessions. For more information, see Section 15.2, "Restore Server Data Context Between Sessions." ServerContext.CacheDataContext Array s N Add elements to the CacheDataContexts array for cases where there is more than one iterator defined in the binding container whose server-side context must be reestablished. The CacheDataContexts array supports the following properties to store the worksheet's cached data context:
CachedServerContexts An array that identifies the attribute binding values to cache and set before the action binding specified by RestoreDataContextActionID is invoked. Each element in the CachedServerContext array supports the CachedAttributeID and RestoredAttributeID properties. CachedAttributeID identifies the attribute binding value to cache in the worksheet. RestoredAttributeID is an optional property for which you specify a value when the destination attribute binding value is different from the source attribute binding value. If you do not specify a value for RestoredAttributeID, the value of CachedAttributeID is used as the destination attribute binding value and its value is set before invoking the action set.
Annotation For more information about this property, see Section A.1, "Frequently Used Properties in the ADF Desktop Integration."
ServerContext.IDAttributeID
Binding
Specifies an attribute binding that uniquely identifies the row displayed in the current worksheet. This property is used at runtime to determine whether the server context has been reestablished properly for non-table type components in the worksheet.
Table A19 (Cont.) Worksheet Properties Name ServerContext.SendParameters Type Boolean EL Description N The default value of this property is FALSE. When set to TRUE, the workbook sends initialization parameters for this worksheet when reestablishing context across multiple sessions. SetupActionID Binding N Specify the ADFm action binding to be invoked before the binding container metadata is retrieved. A value for this property is optional. If two, or more, worksheets are using the same page definition, the action binding specified for the last worksheet will be invoked. Hence, create a page definition for each worksheet and do not specify a page definition to multiple worksheets. Title String Y Specifies an EL expression that resolves to a string and sets the name of the worksheet. At design time, the EL expression can be of any length and can include the following special characters: [ ] \ / * ? At runtime, the evaluated string can display a maximum of 31 characters and ignores the above special characters. If the length of the evaluated string exceeds 31 characters, the extra characters are truncated and are not displayed. Note that the Title property does not support binding parts in the EL expression. The expected usage is a resource-type expression. Ensure that the EL expressions you write for the Title property generate unique values for each worksheet at runtime and contain fewer than 31 characters.
B
B
Section B.1, "Guidelines for Creating EL Expressions" Section B.2, "EL Syntax for ADF Desktop Integration Components" Section B.3, "Attribute Control Hints in ADF Desktop Integration"
Literal values that evaluate correctly to the type expected for the Oracle ADF component property. The following list describes some examples: Boolean values true and false Integer values such as -1, 0, and 100 String values such as hello world
Strings that contain one or more valid EL expression parts. The following list shows examples of valid syntax: #{row.bindings.ProductId.inputValue} #{components.TAB416222534.errors} #{res['excel.saveButton.label']}
A valid Excel formula. An Excel formula string must start with the = character. If the literal string includes an #{...} expression, ADF Desktop Integration evaluates this expression first and inserts the resulting value into the Excel formula string. Excel then evaluates the Excel formula. Note the following points if you write an EL expression: Excel formula elements must not be used inside an #{...} expression. EL expressions should not contain references to Excel cells because EL expressions are managed within ADF configuration. Excel cannot update the ADF configuration if the referenced cell moves. A workaround is to define a named cell reference or range using the Name box in the Excel Formula Bar. You can reference the named cell reference or named cell range reference from
B-1
an EL expression. For information about defining named cell references or ranges, see Excel's documentation.
EL expressions in a page definition file For information about the syntax that you use to write EL expressions in a page definition file, see Section 4.3, "Working with Page Definition Files for an Integrated Excel Workbook."
EL expressions that include Excel formulas Ensure that any Excel formula included in an EL expression has no more than 255 characters. This also applies to formulas used to set conditional values to component properties.
"unknown"
Worksheet errors at runtime #{worksheet.errors} For more information about worksheet errors, see Section 12.4, "Error Reporting in an Integrated Excel Workbook."
Workbook initialization parameters #{workbook.params.parameterName} where parameterName is the name of the workbook initialization parameter. For information about using these parameters, see Section 14.5, "Passing Parameter Values from a Fusion Web Application Page to a Workbook."
#{resourceBundleAlias['resourceBundleKey']} where resourceBundleAlias is the alias of the resource bundle and resourceBundleKey is the string key value. For more information about resource bundles, see Section 10.2, "Using Resource Bundles in an Integrated Excel Workbook." Table B2 describes the supported syntax and properties for Oracle ADF control bindings. For information about the attribute control hints (controlHint) that ADF Desktop Integration supports, see Table B3. You can use the expression builder described in Section 5.8, "Using the Expression Builder" to generate some of the EL expressions described in Table B2. You have to write some other EL expressions as indicated in Table B2.
Table B2 Expression Properties and Syntax for Oracle ADF Control Bindings Component Type Object Property Attribute Attribute control hint Value at Design Time ""
Syntax Use the expression builder to generate EL expressions with the following syntax: #{bindings.attributeID} #{bindings.attributeID.label} #{bindings.attributeID.hints.controlHint} You can also write the previous EL expressions in addition to the following EL expression: #{bindings.attributeID.inputValue} Use the expression builder to generate EL expressions with the following syntax: #{bindings.ListID} #{bindings.ListID.label} #{bindings.ListID.hints.controlHint} Write EL expressions with the following syntax for a column in a table-type component #{row.bindings.attributeID.inputValue} Write an EL expression with the following syntax when adding a dynamic column to an ADF Table component as described in Section 7.16, "Adding a Dynamic Column to Your ADF Table Component": #{bindings.TreeID.[TreeNodeID].AttributeNamePrefix*.input Value} #{bindings.TreeID.AttributeNamePrefix*.inputValue} #{bindings.TreeID.[TreeNodeID].hints.AttributeNamePrefix* .controlHint} #{bindings.TreeID.[TreeNodeID].hints.AttributeNamePrefix* .label} A value for AttributeNamePrefix and [TreeNodeID] is optional while * is required.
List
""
Table.Colum inputValue n
""
B-3
The ADF Desktop Integration attribute control hints are based on information available in the web application's model configuration. ADF Desktop Integration supports view object or entity object hint values, but does not support programmatic overrides of hint values if they are calculated at a row-by-row level at runtime.
C
C
This appendix provides describes how to troubleshoot an integrated Excel workbook and generate log files when you encounter problems during development. It also describes possible solutions for a number of errors and problems (such as version mismatch, 404 error, and Oracle ADF tab not visible in integrated Excel workbook) that you may encounter. This appendix includes the following sections:
Section C.1, "Verifying That Your Fusion Web Application Supports ADF Desktop Integration" Section C.2, "Verifying End-User Authentication for Integrated Excel Workbooks" Section C.3, "Generating Log Files for an Integrated Excel Workbook" Section C.4, "Common ADF Desktop Integration Error Messages and Problems"
Note:
The property inspector does not validate that values you enter for a property or combinations of properties are valid. Invalid values may cause runtime errors. To avoid runtime errors, make sure you specify valid values for properties in the property inspector. For more information about the property inspector, see Section 5.6, "Using the Property Inspector."
C.1 Verifying That Your Fusion Web Application Supports ADF Desktop Integration
Using a specific URL, you can verify that the Fusion web application is running the ADF Desktop Integration remote servlet (adfdiRemote), and the version of ADF Desktop Integration. This information can be useful if you encounter errors with an integrated Excel workbook. For example, you can determine whether the ADF Desktop Integration remote servlet is running when you are troubleshooting an integrated Excel workbook. To verify that the ADF Desktop Integration remote servlet is running: 1. Log on to the Fusion web application.
2.
Type the concatenated values of the workbook properties WebAppRoot and RemoteServletPath into the address bar of your web browser. This corresponds to a URL similar to the following:
C-1
http://hostname:7101/FusionApp/adfdiRemoteServlet If the ADF Desktop Integration remote servlet is running, a web page returns displaying a message similar to Figure C1.
Figure C1 ADF Desktop Integration Remote Servlet
HTTP filter and the ADF Desktop Integration remote servlet on the web server (server-side logging) For more information about server-side logging, see Section C.3.1, "About Server-Side Logging."
Excel workbook which you integrate with your Fusion web application (client-side logging) For more information about client-side logging, see Section C.3.2, "About Client-Side Logging."
Console Displays the Logging Console window, which enables you to review the recent log entries while you are developing and testing the integrated Excel workbook. The console displays entries that are logged while the console is open. Figure C3 illustrates the Logging Console window with error log entries. The console is a resizable, non-modal window with a buffer size of 64,000 characters. When the buffer is full, the old entries are removed. To save log entries, select and copy them to a text file.
The dialog has the following buttons: Set Level: Click to set the log output level. The button opens the Logging Output Level dialog, where you can choose the desired log output level. Clear: Click to clear the log buffer.
C-3
A common Logging Console window logs entries for all open integrated Excel workbooks.
Set Output Level Prompts you to choose the log output level. Table C1 describes the log levels that client-side logging supports.
Client-Side Logging Levels Description Captures critical information. Captures information about severe errors and exceptions. Captures irrecoverable conditions. Captures lifecycle and control flow events. Captures detailed information about the execution flow of the application. No logs are captured. This is the default value.
Note:
The log output level applies to all listeners for a given logger.
Add Log Output File Creates a new temporary logging listener to direct logging output to the specified file or format. In the Add New Temporary Logging Output File dialog, choose the desired file output type (text or XML), and specify the path and file name of the log output file.
The temporary listener directs the logging output for the current Excel session only, and is not registered in the ADF Desktop Integration configuration file. After you close the integrated Excel workbook, the temporary listener is removed.
Note: When you click the Add Log Output File button, a new listener is created. The new listener does not replace any existing listener defined in the ADF Desktop Integration configuration file, or any other temporary listener.
Refresh Config Reloads the ADF Desktop Integration configuration file. The ADF Desktop Integration configuration file determines the type of information logged by ADF Desktop Integration. It also determines the location and the output format of the log file. For more information about the creation and configuration of the ADF Desktop Integration configuration file, see Section C.3.2.2, "About the ADF Desktop Integration Configuration File."
C-5
In the Control Panel, click System, and then Advanced System Settings. In the Advanced tab of System Properties dialog, click Environment Variables. In the Environment Variables dialog, click New under the User variables for username input field, and add variables as described in the Table C2.
User Environment Variables to Configure Logging With a value... That defines the directory path and file name for the XML file that captures logging information. The directory that you specify here must exist before you add the adfdi-common-file variable. The generated log file will be in XML format.
Table C2
adfdi-common-level 5.
Click OK.
C.3.2.4 What You May Need to Know About the adfdi-common Object
The adfdi-common object is an instance of the TraceSource class from the System.Diagnostics namespace in the Microsoft .NET Framework. This object is used to generate log files that capture information about events triggered by the Excel workbook that you integrate with your Fusion web application. To know the location of the log file, check the Log Files attribute in the Properties tab of the About dialog. For more information about the TraceSource class, see Microsoft Developer Network documentation.
ADF Desktop Integration client, see Section 3.4, "Installing ADF Desktop Integration." Error message: 404 Error - servlet not found Cause: The web.xml deployment descriptor settings are not in sync with Workbook.RemoteServletPath property value. Action: Open Workbook Properties editor and verify the Workbook.RemoteServletPath property value. Error message: Programmatic access to Visual Basic Project is not trusted Cause: Macro settings in Excel are not enabled. Action: Verify that the Trust access to the VBA project object model checkbox in the Trust Center dialog is enabled. For more information, see Section 3.3, "Configuring Excel to work with ADF Desktop Integration." Problem: Oracle ADF tab is not visible in your integrated Excel Workbook after installing ADF Desktop Integration Cause: The ADF Desktop Integration add-in is not enabled in Excel. Action: Enable the ADF Desktop Integration add-in in the Excel Options dialog. In Excel, click the Microsoft Office button, and then click Excel Options to open the Excel Options dialog. In the Add-Ins tab, open the Manage dropdown list, choose COM Add-ins, and click Go. In the COM Add-ins dialog, select the Oracle ADF Desktop Integration Add-in for Excel checkbox and click OK. For information about all ADF Desktop Integration error messages, see Oracle Fusion Middleware Error Messages Reference. If you are a system administrator, you should also see the "Common ADF Desktop Integration Error Messages and Problems" section in Administering Oracle ADF Applications.
C-7
D
D
Section D.1, "Configuring the ADF Desktop Integration Servlet" Section D.2, "Configuring the ADF Desktop Integration Excel Download Filter" Section D.3, "Examples in a Deployment Descriptor File"
Note:
Adding ADF Desktop Integration and ADF Library Web Application Support to your desktop integration project automatically generates the entries in the web.xml file discussed in this appendix. For more information, see Section 4.2, "Adding an Integrated Excel Workbook to a Fusion Web Application."
Click the Servlets page, and then click the Add icon to create a row entry in the Servlets table. The icon is in the top-right corner of the servlets table. Enter the values as described in Table D1 to enable the adfdiRemote servlet on the Fusion web application.
Table D1
Values to Enable adfdiRemote Servlet Enter this value... adfdiRemote Servlet Class oracle.adf.desktopintegration.servlet.DIRemoteS ervlet
3.
In Servlets page, click the Servlet Mappings tab, and then click the Add icon to create a row in the Servlet Mapping table. Enter the value as described in Table D2 to add a URL pattern for the adfdiRemote servlet in the Fusion web application. The value that you enter must match the value that you specify in the integrated Excel workbook for the RemoteServletPath workbook property. Note that values are case sensitive.
Table D2
Values to Add A URL Pattern to adfdiRemote Servlet Enter this value... /adfdiRemoteServlet
Figure D1 displays the Servlets page of web.xml of Summit sample application for ADF Desktop Integration.
Figure D1 Servlets Page of Deployment Descriptor
4.
Click the Filters page, and verify that whether a adfBindings filter exists in the Filters table. If an entry exists, select it and proceed to the next step. If there is no such entry, then click the Add icon to create a row entry in the Filters table. The icon is available in the top-right corner of the filters table.
Enter the values as described in Table D3 to add the ADF binding filter to the adfdiRemote servlet.
Table D3 Values to Add Binding Filter to adfdiRemote Servlet Enter this value... adfBindings oracle.adf.model.servlet.ADFBindingFilter
In Filters page, click the Filter Mappings tab, and then click the Add icon to create a row in the Filter Mapping table. Enter the values as described in Table D4 to add the mapping filter to the adfdiRemote servlet. The filter mapping must match with the Servlet name in Step 2.
Table D4
Values to Add Mapping Filter to adfdiRemote Servlet Enter this value... Servlet adfdiRemote
Figure D2 displays the Filters page of web.xml of Summit sample application for ADF Desktop Integration.
Figure D2 Filters Page of Deployment Descriptor
6.
Save the deployment descriptor file, and then rebuild your ADF Desktop Integration project to apply the changes you made.
D-3
MW_HOME\oracle_common\modules\oracle.adf.desktopintegration_ 12.1.2 where MW_HOME is the Middleware Home directory. You configure an entry in the deployment descriptor file (web.xml) of your Fusion web application so that the application invokes the HTTP filter to make changes in an integrated Excel workbook before the integrated Excel workbook is downloaded by the end user from the Fusion web application. These changes ensure that the integrated Excel workbook functions correctly when the end user opens it. The HTTP filter makes the following changes:
WebAppRoot Sets the value for this property to the fully qualified URL for the Fusion web application from which the end user downloads the integrated Excel workbook.
Workbook mode Changes the integrated Excel workbook mode to runtime mode in case the workbook was inadvertently left in design mode or test mode.
Note: If you choose not to use the adfdiExcelDownload filter, you can instead use the workbook administration tool to set the WebAppRoot property on your workbooks. For more information, see the "Using the Workbook Administration Tool" in Administering Oracle ADF Applications.
By default, JDeveloper adds the HTTP filter to your ADF Desktop Integration project when ADF Desktop Integration is enabled in your project. To configure the HTTP filter: In JDeveloper, locate and open the deployment descriptor file (web.xml) for your ADF Desktop Integration project. Typically, this file is located in the WEB-INF directory of your project.
2.
1.
Click the Filters page, and verify that an adfBindings filter exists in the Filters table. If an entry exists, select it and proceed to the next step. If there is no such entry, then click the Add icon to create a row entry in the Filters table. Enter the values as described in Table D5 to create a filter, or configure the values to modify the existing HTTP filter.
Table D5
Properties to Configure HTTP Filter Enter this value... adfdiExcelDownload oracle.adf.desktopintegration.filter.DIExcelDow nloadFilter (Optional) In General Filter tab, enter a display name for the filter that appears in JDeveloper. (Optional) In General Filter tab, enter a description of the filter.
In the Filters page, click the Filter Mappings tab, and then click the Add icon to create a row in Filter Mapping table.
Add a filter mapping for integrated Excel workbooks that use the default file format (.xlsx) by entering values as described in Table D6.
Table D6 Properties to Configure Filter Mappings Enter this value... URL Pattern *.xlsx No value is required for this property.
Add another filter mapping for integrated Excel workbooks that use the macro-enabled workbook format (.xlsm) by entering values as described in Table D7.
Properties to Configure Filter Mappings Enter this value... URL Pattern *.xlsm No value is required for this property.
Table D7
Figure D3 displays the Filters page of web.xml of Summit sample application for ADF Desktop Integration.
Figure D3 Filters Page of Deployment Descriptor
5.
Click the Application page, expand MIME Mappings section, and click the Add icon. Add a MIME type for integrated Excel workbooks that use the default file format (.xlsx) by entering values as described inTable D8.
Table D8
D-5
Table D8 (Cont.) Properties to Add MIME Mappings For this property... MIME Type Enter this value... application/vnd.openxmlformats-officedocument.s preadsheetml.sheet
6.
Add another MIME type for integrated Excel workbooks that use the macro-enabled workbook format (.xlsm) by entering values as described in Table D9.
Properties to Add MIME Mappings Enter this value... *.xlsm application/vnd.ms-excel.sheet.macroEnabled.12
Table D9
Figure D4 displays the Application page of web.xml of Summit sample application for ADF Desktop Integration.
Figure D4 Application Page of Deployment Descriptor
7.
Save the deployment descriptor file, and then rebuild your ADF Desktop Integration project to apply the changes you made.
While updating filter and filter mapping information in the web.xml file, ensure that the filter for ADF Library Web Application Support (<filter-name>ADFLibraryFilter</filter-name>) appears below the adfdiExcelDownload filter entries, so that integrated Excel workbooks can be downloaded from the Fusion web application.
D-7
E
E
Table E1
String Keys and Values in the Reserved Resource Bundle English value in the ADF Desktop Integration reserved resource bundle Upload Options Specify options to use during the Upload operation On failure, continue to upload subsequent rows Download all rows after successful upload Download Do you wish to discard the pending changes? Row limit exceeded Initialize Do you wish to discard the pending changes? Clear all data This command will log you out of your current session and clear all the data from all worksheets in the workbook. Are you sure? Logout You have been logged out from your current session. Upload
Area where string key value appears at runtime Upload Options Upload Options Upload Options Upload Options Table.Download Table.Download Table.Download
String key UPLOAD_OPTIONS_TITLE UPLOAD_OPTIONS_PROMPT UPLOAD_OPTIONS_CONTINUE_ON_ FAIL_LABEL UPLOAD_OPTIONS_DOWNLOAD_AFTER_ LABEL DOWNLOAD_OVERWRITE_TITLE DOWNLOAD_OVERWRITE_PROMPT ROWLIMIT_WARNINGS_TITLE
Comments
Table.Initialize INITIALIZE_OVERWRITE_TITLE Table.Initialize INITIALIZE_OVERWRITE_PROMPT Workbook.ClearAl CLEARDATA_CONFIRM_TITLE lData Workbook.ClearAl CLEARDATA_CONFIRM_PROMPT lData
E-1
Table E1
(Cont.) String Keys and Values in the Reserved Resource Bundle English value in the ADF Desktop Integration reserved resource bundle One or more dynamic columns is no longer available, do you wish to continue? No updates detected Record not found Cannot insert record more than once See Error Detail {0} {0} is a batch number {0} is a batch number {1} is an error message
Comments
Table status
TABLE_COMMIT_FAILURE_DETAILS_2
Table status Table status Table status Table status Table status Table status Table status Table status Table status Table status Table status Table status Table status Table status Table status Table status Table errors Worksheet errors Table status Table errors Worksheet errors Worksheet errors Worksheet errors
TABLE_UPLOAD_ROW_UPDATE_SUCCESS TABLE_UPLOAD_ROW_INSERT_SUCCESS TABLE_UPLOAD_ROW_UPDATE_FAILURE TABLE_UPLOAD_ROW_INSERT_FAILURE TABLE_DELETE_ROW_FAILURE TABLE_ROW_KEY_VALUE_INVALID TABLE_DOWNLOAD_FAILURE TABLE_DOWNLOAD_ROW_FAILURE TABLE_DOWNLOAD_FLAGGED_FAILURE TABLE_DOWNLOAD_FOR_INSERT_ FAILURE MESSAGE_DETAILS_NONE MESSAGE_DETAILS_ROW_TITLE MESSAGE_DETAILS_ROW_PROMPT MESSAGE_DETAILS_TABLE_TITLE MESSAGE_DETAILS_TABLE_PROMPT MESSAGE_DETAILS_HELP_LABEL
Row updated successfully Row inserted successfully Update failed Insert failed Delete failed Key value invalid Download failed Row download failed Download flagged rows failed Download for insert failed No error details available Row Errors Errors for this row: Table Errors Error details for this table: Click on each error to reveal additional information Appears in the error list.
MESSAGE_LABEL_DEFAULT_CONTEXT
Action
Table E1
(Cont.) String Keys and Values in the Reserved Resource Bundle English value in the ADF Desktop Integration reserved resource bundle A problem has occurred while retrieving the error details. The information is no longer available. {0} failed {0} is a context label
Comments
Worksheet errors
MESSAGE_LABEL_FAILED_1
Edit Options Enter a value for WebAppRoot. For example: http://localhost:1234/My App. Web App Root Changing the Web App Root will log you out of your current session and clear all the data from all worksheets in the workbook. Are you sure?
Note: The keys listed in Table E1 cannot be used in EL expressions of the following syntax:
#{_ADFDIres['key']}
E-3
F
F
Object Java Types java.lang.Boolean java.lang.Double java.lang.Float java.lang.Integer java.lang.Long java.lang.Short java.lang.String java.math.BigDecimal java.sql.Date java.sql.Time java.sql.Timestamp java.util.Date oracle.jbo.domain.Date oracle.jbo.domain.Number oracle.jbo.domain.RowID oracle.jbo.domain.Timestamp oracle.jbo.domain.TimestampLTZ
Java Data Types Supported By ADF Desktop Integration F-1
oracle.jbo.domain.TimestampTZ
Note: Using data types not listed in this appendix will generate error at runtime.
G
G
Section G.1, "About the Temporary Row Object" Section G.2, "About ADF Desktop Integration Model API" Section G.3, "ADF Desktop Integration Model API Classes and Methods"
The tree node's iterator result set does not have any data rows available. This could be because of a query returning zero rows. In a parent-child relationship, if the foreign key has not been populated in the parent table, the link between parent and child tree node may not contain actual rows.
There may be certain cases when, even though there is no actual row available on the server, you still want to allow the end user to enter values in the worksheet and upload them to the server. During upload, ADF Desktop Integration creates a temporary row object and stores the values uploaded from the worksheet row. Using the ADF Desktop Integration Model API, you can write custom Java code to access the temporary row object and collect its values. To call your custom Java code during upload, you must expose your custom Java code through a pageDef action binding and then configure the ADF Table component's
G-1
The ADF Desktop Integration Model API is not supported for EJB or Toplink data controls.
For more information about the classes and methods available in the API, see Section G.3, "ADF Desktop Integration Model API Classes and Methods."
G.2.1 How to Add ADF Desktop Integration Model API Library to Your JDeveloper Project
You typically add the ADF Desktop Integration Model API Library to your application's data model project. The library is an independent library, not included with any feature. You can add it through Project Properties dialog box. To add ADF Desktop Integration Model API library to your project: 1. In the Applications window, right-click the data model project and choose Project Properties.
2. 3.
In the Project Properties dialog, select Libraries and Classpath to view the list of libraries available. Click Add Library and in the Add Library dialog, select the ADF Desktop Integration Model API library.
4. 5.
Click OK. The library name adds to the Classpath Entries list. Click OK to close the Project Properties dialog box.
G-3
H
H
This appendix describes the actions the end user would be performing while using your application and integrated Excel workbook, such as installing runtime edition of ADF Desktop Integration, importing data from non-integrated Excel workbook, making changes in the workbook at runtime, and handling time zone conversion of date-time values in the workbook. The actions described in this appendix assume that you have developed a functioning Fusion web application. This appendix includes the following sections:
Section H.1, "Installing, Upgrading, and Removing the Runtime Edition of ADF Desktop Integration" Section H.2, "Importing Data from a Non-Integrated Excel Worksheet" Section H.3, "Removing Personal Information" Section H.4, "Editing an Integrated Excel Workbook at Runtime" Section H.5, "Limitations of an Integrated Excel Workbook at Runtime" Section H.6, "Using An Integrated Excel Workbook" Section H.7, "Handling Time Zone Conversion"
H.1 Installing, Upgrading, and Removing the Runtime Edition of ADF Desktop Integration
End users can install the runtime edition of ADF Desktop Integration using the client installer. When the ADF Desktop Integration client installer runs, it verifies whether the required software is installed on the system. For more information about the required software, see the following:
Section 3.2, "Required Oracle ADF Modules and Third-Party Software" Section 3.3, "Configuring Excel to work with ADF Desktop Integration"
Notes:
You cannot install the Runtime edition of ADF Desktop Integration from JDeveloper. JDeveloper is not required to install the runtime edition of ADF Desktop Integration.
H-1
Installing, Upgrading, and Removing the Runtime Edition of ADF Desktop Integration
Extract the contents of adfdi-excel-runtime-client-installer.zip to a temporary directory on the end user's local file system (for example, D:\Oracle\ADFDI_Client). Note that the fully qualified path of the temporary directory must be less than 248 characters.
3.
Run the setup.exe file located in the extracted directory of the adfdi-excel-runtime-client-installer.zip file. Figure H1 shows an example of the setup.exe file location on a local system, and the installation of runtime edition.
4. 5.
Follow the instructions that appear in the dialog boxes launched by setup.exe to successfully install the required components. If prompted, click Yes to restart the system and complete the setup of ADF Desktop Integration.
WARNING: After you install the runtime edition of ADF Desktop Integration, do not delete the directory where you copied the client installer files. You can delete the files after removing the runtime edition of ADF Desktop Integration from the system.
In the Control Panel, select and open Programs and Features. Select the Oracle ADF Desktop Integration Runtime add-in for Excel entry in the Uninstall or change a program window, and click Uninstall.
H.1.3 How to Upgrade the Runtime Edition of ADF Desktop Integration On a Local System
To upgrade the runtime edition of ADF Desktop Integration, uninstall the old client version, and install the new version. For more information about uninstalling the runtime edition, see Section H.1.2, "How to Remove the Runtime Edition of ADF Desktop Integration," and for more information about installing the runtime edition, see Section H.1.1, "How to Install Runtime Edition of ADF Desktop Integration." If the runtime edition of ADF Desktop Integration is installed from a shared file server or a web server, by default, Excel checks the server for ADF Desktop Integration updates when it is launched and if 24 hours have elapsed since the last check for updates. If you do not wish to wait 24 hours and want to check the update manually, you can do so from the Microsoft Windows Control Panel. To upgrade the Runtime edition of ADF Desktop Integration manually: 1. Click the Windows Start button, and then choose Control Panel.
2. 3. 4.
In the Control Panel, select and open Programs and Features. Select the Oracle ADF Desktop Integration Runtime Add-in for Excel entry in the Uninstall or change a program window. With the entry selected, click the Update Information link.
Note:
If the runtime edition of ADF Desktop Integration is installed from a web server, open the Update Information link in Internet Explorer to run the installer. Other browsers are not supported.
5.
Follow the instructions that appear in the dialog boxes to successfully upgrade ADF Desktop Integration.
the ADF Table component prior to invoking the ADF Table component's Upload action. To prepare data in a non-integrated Excel workbook: 1. Arrange the layout of data in a non-integrated Excel worksheet to match the layout of the ADF Table component in the integrated Excel workbook. For example, if an ADF Table component contains columns such as Product, Price, and Description, reproduce this layout in the non-integrated Excel worksheet.
Tip: Copy the column headers from the ADF Table component to the non-integrated Excel worksheet.
2. 3.
Use functionality of Excel to import the rows of data into the non-integrated Excel worksheet in rows under the columns arranged in Step 1. Row values that will be inserted into ADF Table component columns that use the TreeNodeList subcomponent must match a choice from the list of values.
Tip: Copy an ADF Table component row from the integrated Excel workbook to another worksheet of the same workbook, as the proper constraints will be defined for such a row and can be reproduced.
To insert data into the ADF Table component from a non-integrated Excel workbook: 1. In the ADF Table component, highlight n existing downloaded rows or new rows at the end of the ADF Table component where n is the number of rows to insert.
2. 3.
Right-click and choose Insert from the context menu. In the non-integrated Excel worksheet, select the cells to insert into the rows of the ADF Table component created in Step 2.
WARNING:
Select the cells in the non-integrated Excel worksheet and not the rows or columns.
4. 5. 6. 7.
In the Excel Ribbon, choose Home > Copy. In the ADF Table component, select the upper left corner cell of the rows inserted in Step 2. In the Excel Ribbon, choose Home > Paste. End users can now invoke the ADF Table component's Upload action using whatever functionality you configured for them as described in Section 7.8, "Configuring an ADF Component to Upload Changes from an ADF Table Component."
For information about removing personal information, see Microsoft Internet Explorer documentation.
Delete a column from an ADF Table or ADF Read-only Table component. Drag and drop cells to move ADF components other than an ADF Button component. Insert new rows into an ADF Table component. Change the order of columns in an ADF Table or ADF Read-only Table component. Insert non-integrated columns between the columns of an ADF Table or ADF Read-only Table component.
However, some changes to a workbook at runtime can corrupt the integration and are not supported. For more information about what changes are not allowed at runtime, see Section H.5, "Limitations of an Integrated Excel Workbook at Runtime."
Moving a column in ADF Table and ADF Read-only Table components If the end user moves a column (for example, using native Excel cut-insert operations) to the right of the last table column, the column is considered to be outside of the table boundaries. ADF Desktop Integration will no longer recognize the column as being part of the table component during subsequent table operations. Instead, to change the last column of a table component at runtime, the end user can perform either of the following actions: Move all columns that are to the right of the desired last column to the left of the desired last column. First, move the desired last column to the immediate left of the current last column, and then move the current last column to the left of the desired last column.
Similar actions should be performed to move a column so that it becomes the left-most column of the table.
Deleting an integrated Excel worksheet If the end user deletes an integrated Excel worksheet, ADF Desktop Integration generates an exception when the end user tries to save the integrated Excel workbook. To resolve the problem, the end user must close and reopen the workbook without saving changes.
Additional known limitations: Excel's Conditional Formatting feature cannot be used effectively with ADF Desktop Integration table components.
H-5
The ADF Button components are disabled when the end user zooms in or out on an integrated Excel worksheet. The ADF Button components are active at 100% zoom only. Due to native Excel behavior, sorting a dependent List of Values column at runtime does not sort the cell list validations properly.
To download all rows after uploading the changed data, ensure that Download all rows after successful upload checkbox is selected in Upload Options dialog box. Before uploading the changes, ensure that the Changed column of all modified rows is marked with an upward pointing triangle. A double-click on the upward pointing triangle character removes it, and the data of the relevant row is not uploaded. To have Excel retain the format of a numeric or date value in a cell formatted with a text style while uploading data, add an apostrophe symbol (') before entering the value. The apostrophe symbol acts as an escape character and is not displayed with the value. Do not delete, edit, or clear any cells in the Key column of the table. Any change to these values can lead to upload failures and data corruption. Do not change Excel's settings for Protect Sheet or Protect Workbook. These settings are available in the Changes group of the Review tab. To erase a value from a cell that is integrated with the web application, clear the cell value instead of deleting the Excel cell. If the Fusion web application is running on the https protocol and you have not installed the security certificate on the client, the integrated Excel workbook gives an error on login and the connection is not established. To establish a connection, you must install the security certificate. If you cannot install the certificate from Excel, open Internet Explorer and navigate to the same website. You will be prompted to install the certificate. Some ADF components may have cells that are configured to respond to a double-click to perform some action. For example, the Status column cells of the ADF Table component. You can also right-click in these cells and select Invoke Action.
Some common actions, such as inserting or deleting a row, and sorting data in ADF Table, are described in the subsequent sections.
H.6.1 How to Insert a Row in an ADF Table Component of an Integrated Excel Workbook
To insert a row in an ADF Table component, insert a full row in the worksheet, and add data in all mandatory columns. For more information, see Section 7.7, "Configuring an ADF Table Component to Insert Data." An ADF Table, with one or more data rows, does not have a placeholder row after the last row of the table. Hence, any data inserted in the cells of the workbook after the last row of the table is not uploaded. To upload data of the row after the last row, you must insert a full Excel row.
To insert a row in an ADF Table component: 1. In the ADF Table component, click the row header, and select the entire row above which you want to insert the new row.
2.
With the row selected, right-click and choose Insert. A new row is inserted above the selected row.
Notes:
Insert a full Excel row between the table headers and the last row of the table. Do not insert the new row after the last row of the table. If the ADF Table has no data rows, the first row of the table acts as a placeholder row.
In the Editing group of the Home tab, click Sort and Filter. Choose the desired sort order from the dropdown list options.
To sort table data based on multiple columns: 1. Select any cell of the table.
2. 3. 4.
In the Editing group of the Home tab, click Sort and Filter, and choose Custom Sort. In the Sort dialog, add the columns, and their order preference. Ensure that the My data has headers checkbox is enabled. Click OK.
If your table does not contain a Flagged column, you will not be able to delete rows from that table.
H-7
end user about the time zone update when the workbook is opened, and then converts the date-time data of the workbook to the current time zone setting of the system. For example, an end user in Arizona (GMT -07:00) downloads the data from the server to the integrated Excel workbook, edits the date-time data in the workbook, saves the data, but does not upload it. Later, the end user travels to Seoul and changes the time zone preference of the computer to GMT +09:00. When the workbook is opened after changing to the Seoul time zone, the end user receives a message, and then all date-time data values in the ADF components are converted from GMT -07:00 (Arizona) to GMT +09:00 (Seoul).