5 Getting Started with the Development Tools
This chapter describes how to use the development tools provided by the Oracle ADF Desktop Integration module. It provides an overview of the authoring environment that Oracle ADF exposes within Excel and goes on to describe how you display and use the different elements of this environment.
This chapter includes the following sections:
5.1 Introduction to the Development Tools
The Oracle ADF Desktop Integration module provides a number of tools that you use to configure Excel workbooks so that they can access Oracle ADF functionality. Before you use these tools, you must know that there are two modes in which you can work while you configure the Excel workbook that you integrate with a Fusion web application. The first mode is design and the second mode is test. In design mode, you use the tools provided by Oracle ADF in Excel to design and configure your integrated Excel workbook. In test mode, you can view and test the changes you make in design mode in the same way that an end user views the published integrated Excel workbook: the difference is that you can switch back to design mode using a button on the Oracle ADF Desktop Integration Designer toolbar.
Figure 5-1 shows the Oracle ADF Desktop Integration Designer toolbar in design mode.
The Oracle ADF Desktop Integration Designer toolbar provides menu buttons that let you invoke the actions that are described in Table 5-1.
Table 5-1 Oracle ADF Desktop Integration Designer Toolbar Menu Options
| Click this button... | To... |
|---|---|
 |
Display the property inspector window to view and edit component properties. |
 |
Delete a component from the Excel worksheet. |
 |
Switch the Excel workbook from design mode to test mode. |
 |
Switch the Excel workbook from 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.3, "Testing Your Integrated Excel Workbook". |
 |
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". |
 |
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, "Reloading a Page Definition File in an Excel Workbook". |
|
Tools |
Use Tools > Reset WorkbookID to reset the value of the For more information, see Section 11.3.1, "How to Reset the Workbook ID". |
Tip:
For quick and easy access to the Oracle ADF Desktop Integration Designer toolbar, you can add it in the Excel's Quick Access toolbar.Table 5-1 displays the Oracle ADF Desktop Integration Designer.
The Oracle ADF Desktop Integration Designer appears in Excel's Document Actions. Use the View > Document Actions options on the Excel Ribbon to control the display of the Oracle ADF Desktop Integration Designer. Table 5-2 lists the view tabs and links that appear in the designer, provides a brief description of each item, and provides a cross-reference to a section that gives more detailed information.
Table 5-2 Overview of the Oracle ADF Desktop Integration Designer
| Designer UI Element | Description |
|---|---|
|
Workbook Properties |
Click to display the Edit Workbook Properties dialog box. This dialog box allows 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. |
|
Worksheet Properties |
Click to display the Edit Worksheet Properties dialog box. This dialog box allows 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. |
|
About Oracle ADF 11g Desktop Integration |
Click to display the About Oracle ADF 11g Desktop Integration dialog box. This dialog box provides a variety of 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. |
|
Bindings |
The bindings palette displays the list of Oracle ADF bindings that you can insert into an Excel worksheet. For information on how to use this palette, see Section 5.2, "Using the Bindings Palette". |
|
Components |
The components palette displays the list of Oracle ADF components that you can insert into an Excel worksheet. For information on how to use this palette, Section 5.3, "Using the Components Palette". |
5.2 Using the Bindings Palette
The bindings palette presents the available Oracle ADF bindings that you can insert into the Excel worksheet. The page definition file for the current Excel worksheet determines what Oracle ADF bindings appear in the bindings palette. Figure 5-3 shows a bindings palette populated with Oracle ADF bindings in the Oracle ADF Desktop Integration Designer. 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.
You use the bindings palette in design mode to insert a binding. When you attempt to insert a binding, the Oracle ADF Desktop Integration module inserts an Oracle ADF component that references the binding you selected. The Oracle ADF Desktop Integration module 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 5-3, 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, you first select the cell that you want 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 control binding and click Insert Binding in the Oracle ADF Desktop Integration Designer.
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. Once you select an Oracle ADF component from the list, a property inspector appears.
5.3 Using the Components Palette
The components palette displays the available Oracle ADF Desktop Integration module components that you can insert into an Excel worksheet. Figure 5-4 shows the components palette as it appears in the Oracle ADF Desktop Integration Designer.
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 and click Insert Component in the Oracle ADF Desktop Integration Designer.
In both 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.
5.4 Using the Property Inspector
The property inspector is a dialog box that allows you to view and edit the properties of Oracle ADF bindings, Oracle ADF components, Excel worksheets, or the Excel workbook. You can open the property inspector in one of the following ways:
-
Select the component or binding, and click the component properties icon in the Oracle ADF Desktop Integration Designer toolbar.
-
Select the component or binding, right-click and choose Edit ADF Component Properties from the context menu.
The property inspector also appears automatically after you insert an Oracle ADF binding or component into an Excel worksheet. Figure 5-5 shows a property inspector window where you can view and edit the properties of an Oracle ADF Button component.
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. The following table describes the buttons that you can use to change how properties display in the property inspector.
| Button | Description |
|---|---|
 |
Use this button to display the properties according to category. |
 |
Use this button to display the properties in an alphabetical list. |
In Figure 5-5, the property inspector displays the properties grouped by category.
5.5 Using the Binding ID Picker
The binding ID picker is a dialog box that allows you to select Oracle ADF bindings at design time to configure the behavior of Oracle ADF components at runtime. You invoke the binding ID picker from the property inspector. The binding ID picker filters the Oracle ADF bindings that appear, based on the type of binding that the Oracle ADF component property accepts. For example, the SuccessActionID property for an ADF Button component supports only action bindings. As a result, the binding ID picker filters the bindings from the page definition file so that only action bindings appear, as illustrated in Figure 5-6.
For more information about Oracle ADF Desktop Integration component properties and the bindings they support, see Appendix A, "Oracle ADF Desktop Integration Component Properties and Actions".
5.6 Using the Expression Builder
You use the expression builder to write Expression Language, or EL, expressions that configure the behavior of components at runtime in the Excel workbook. You invoke the expression builder from the property inspector of component properties that support EL expressions. For example, the Label property in Figure 5-7 supports EL expressions and, as a result, you can invoke the expression builder to set a value for this property.
You can reference bindings in the EL expressions that you write. Note that the expression builder does not filter bindings. It displays all bindings that the page definition file exposes. See Table 4-1 to identify the types of bindings that each Oracle ADF Desktop Integration component supports.
To add an expression in the Expression box, select the item and click Insert Into Expression. You can also double-click the item to add it in the Expression box. Table 5-3 describes the folders available in the expression builder.
Table 5-3 Expression Builder Folders
| Folder Name | Description |
|---|---|
|
Bindings |
Lists the bindings supported in the Oracle ADF Desktop Integration module from the current worksheet's page definition. |
|
Components |
Lists the ADF components available in the current worksheet. |
|
Resources |
Lists the resource bundles registered in |
|
Styles |
Lists all Excel styles defined in the current workbook. For more information, see Section 9.2, "Working with Styles". |
|
Workbook |
Lists parameters defined in |
|
Worksheet |
Lists the |
|
Excel Functions |
Lists sample Excel functions that you can use with Oracle ADF Desktop Integration. For more information, see Excel's documentation. |
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 the Oracle ADF Desktop Integration module and guidelines on how you write these expressions, see Appendix B, "Oracle ADF Desktop Integration EL Expressions".
5.7 Using the Web Page Picker
Use the web page picker to select a web page from your Fusion web application. At runtime, an Oracle ADF component, for example an Oracle ADF Button component, can invoke the web page that you associate with the Oracle ADF component.
You can invoke the web page picker when you add a Dialog action to an action set in the Action Collector Editor. You use the web page picker to specify a web page for the Page property of the Dialog action, as illustrated in Figure 5-8. You can also invoke the web page picker when you set a value for the ProtectedWebPage workbook property.
For more information about displaying web pages in your integrated Excel workbook, see Section 8.4, "Displaying Web Pages from a Fusion Web Application".
5.8 Using the File System Folder Picker
Use the file system folder picker to navigate over the Windows file system and select folders. You use this picker to specify values for the following workbook properties:
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.4.2, "How to Open an Excel Workbook for the First Time".
Figure 5-9 shows the file system folder picker selecting a value for the ApplicationHomeFolder workbook property.
5.9 Using the Page Definition Picker
Use the page definition picker to select the page definition ID of a page definition file and associate the file with a worksheet. The picker appears the first time that you activate a worksheet in an integrated Excel workbook. It can also be invoked when you attempt to set a value for the worksheet property, PageDefinition, as illustrated in Figure 5-10.
For more information about page definition files, see Section 4.3, "Working with Page Definition Files for an Integrated Excel Workbook".
5.10 Using the Collection Editors
The Oracle ADF Desktop Integration module uses collection editors to manage the properties of elements in a collection. The title that appears in a collection editor's title bar describes what the collection editor allows you to configure. Examples of titles for collection editors include CacheDataContext Collection Editor, TableColumn Collection Editor, and the Action Collection Editor. These collection editors allow you to configure collections of cached data, table columns in the ADF Table component, and actions in an action set. Figure 5-11 shows the collection editor that configures an action set for the Search button that appears at runtime in the Master Price List module's EditPriceList-DT.xlsx workbook.
Tip:
Write a description in the Annotation field for each element that you add to the Action Collection Editor. 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 the Oracle ADF Desktop Integration module generates.