1. Open the Fusion web application in JDeveloper.
2. In the Applications window, select the user interface project, such as ViewController, to which you want to add the page definition file.
3. From the File menu, choose New > From Gallery.
4. In the New Gallery, expand Client Tier, select ADF Desktop Integration, then ADF Desktop Integration Page Definition, and then click OK.

   Figure 4-1 shows the New Gallery with ADF Desktop Integration category and the ADF Desktop Integration Page Definition option.

   Figure 4-1 New Gallery - ADF Desktop Integration Page Definition

   

   Click OK.

5. In the Create ADF Desktop Integration Page Definition dialog, if required, edit the page definition file name.
6. Click OK.

JDeveloper adds the page definition into the Fusion web application and opens the new page definition's editor. Figure 4-2 shows the ViewController project with the new page definition in the Applications window.

Figure 4-2 adfdiPageDefn.xml in Applications window

For information about working with page definition files, see Working with Page Definition Files in Developing Fusion Web Applications with Oracle Application Development Framework.

JDeveloper creates the DataBindings.cpx file the first time you add a page definition file in the JDeveloper project using the procedure described in How to Create ADF Desktop Integration Page Definition File.

The DataBindings.cpx file defines the binding context for the Fusion web application and provides the configuration from which the Oracle ADF bindings are created at runtime. Information about working with this file can be found in Working with the DataBindings.cpx File of Developing Fusion Web Applications with Oracle Application Development Framework.

[ADFDI-05530] unable to initialize worksheet: MyWorksheet
[ADFDI-05517] unable to find control MyBindingThatWasRemoved

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.

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 4-3 shows the bindings in the ExcelCustomers.xml page definition file and the same bindings in the worksheet of the EditCustomers-DT.xlsx workbook.

Figure 4-3 Page Definition Bindings in JDeveloper and 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 separate page definition file with each worksheet as described in 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.

1. Open the Fusion web application in JDeveloper.
2. In the Applications window, select the user interface project, such as ViewController, to which you want to add the new integrated Excel workbook.
3. From the File menu, choose New > From Gallery.
4. In the New Gallery, expand Client Tier, select ADF Desktop Integration, then Microsoft Excel Workbook, and then click OK.

   Figure 4-4 shows the New Gallery with ADF Desktop Integration category and the Microsoft Excel Workbook option.

   Figure 4-4 New Gallery - Microsoft Excel Workbook

   

   Click OK.

5. In the Create ADF Desktop Integration-Enabled Excel Workbook dialog, verify the desired location and type a unique workbook name. Consider adding a suffix of -DT to help with publishing later. For example, MyWorkbook-DT.xlsx.

   By default, the integrated Excel workbook is saved as adfdi-workbook-DT.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 applications.

   Later, ADF Desktop Integration removes suffixes, such as -DT, when you publish the finalized integrated Excel workbook for distribution so that end users see meaningful filenames. For example, the Summit sample application publishes the workbook to edit customers using the EditCustomers.xlsx filename rather than EditCustomers-DT.xlsx.

6. Click OK.

JDeveloper adds the integrated Excel workbook into the Fusion web application, and automatically enables the project with ADF Desktop Integration. Figure 4-5 shows the ViewController project.

Figure 4-5 adfdi-workbook-DT.xlsx in Applications window

Description of "Figure 4-5 adfdi-workbook-DT.xlsx in Applications window"

1. Open the integrated Excel workbook.

   • If you have saved the workbook with other files of the Fusion web application, the Page Definition dialog automatically appears, as illustrated in Figure 4-6.

     Figure 4-6 Page Definition Dialog

     
     Description of "Figure 4-6 Page Definition Dialog"

     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 How to Manually Configure a New Integrated Excel Workbook.

2. In the Workbook group of the Oracle ADF tab, click Workbook Properties.
3. 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 4-7 shows the web context root used for the Summit sample application for ADF Desktop Integration in JDeveloper and integrated Excel workbook.

     Figure 4-7 Setting Web Context Root in JDeveloper and Integrated Excel Workbook

     
     Description of "Figure 4-7 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 your system using the Summit sample application for ADF Desktop Integration:

     http://localhost:7101/summit

     For information about how to verify that the Fusion web application is online and that it supports ADF Desktop Integration, see 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 information about securing the Fusion web application, see Securing Web Applications in 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 4-8 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.

   Figure 4-8 Edit Workbook Properties Dialog

   
4. Click OK.

   Note:

   In Step 1, if the fully qualified path of the selected page definition file exceeds the Windows path length limit, a warning message appears when the Workbook Properties dialog is closed, and the page definition will not load.

5. Save the Excel workbook.

1. While the Excel workbook is in design mode, click the Home tab in the Excel ribbon, and then choose Insert > Insert Sheet in the Cells group.
2. 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.

1. In Excel, open the workbook.
2. In the Workbook group of the Oracle ADF tab, click Workbook Properties.
3. In the Enable Workbook dialog, click Yes, as shown in Figure 4-9.

   Figure 4-9 Enable Workbook Dialog

   

   ADF Desktop Integration prepares your workbook, displays the ADF Desktop Integration Designer task pane, and opens the Browse For Folder dialog. See How to Manually Configure a New Integrated Excel Workbook.

4. Save the workbook.

1. Open the integrated Excel workbook.

   The Browse For Folder dialog automatically appears, as illustrated in Figure 4-10.

   Figure 4-10 Browse For Folder Dialog

   
   Description of "Figure 4-10 Browse For Folder Dialog"

   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. In the Workbook group of the Oracle ADF tab, click Workbook Properties.
3. In the Edit Workbook Properties dialog, configure the properties as described in Step 3 of How to Configure a New Integrated Excel Workbook.
4. Click OK.
5. In the Workbook group of the Oracle ADF tab, click Worksheet Properties.
6. 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 4-11.

   Figure 4-11 Page Definition Dialog

   
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. Save the Excel workbook.

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. In the Project Properties dialog, select Features to view the list of available features.
4. Click Add Features.
5. In the Add Features dialog, select the ADF Desktop Integration feature and add it to the Selected list, as shown in Figure 4-12.

   Figure 4-12 Add Features Dialog

   
   Description of "Figure 4-12 Add Features Dialog"
6. Click OK to close the Add Features dialog.
7. Click OK to close the Project Properties dialog.

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

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

If you want to distribute integrated workbooks by adding them to ADF library files, add ADF Library web application support to the Fusion web application. See Packaging a Reusable ADF Component into an ADF Library in Developing Fusion Web Applications with Oracle Application Development Framework.

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

Figure 4-13 shows the Filters tab of the overview editor of the web.xml in JDeveloper.

Figure 4-13 Filters Tab of web.xml

Description of "Figure 4-13 Filters Tab of web.xml"

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

Figure 4-14 ADFLibraryFilter Using include-extension-list Parameter

Description of "Figure 4-14 ADFLibraryFilter Using include-extension-list Parameter"

For information about web.xml, see ADF Desktop Integration Settings in the Web Application Deployment Descriptor.