Oracle® Fusion Middleware Desktop Integration Developer's Guide for Oracle Application Development Framework 11g Release 1 (11.1.1) E10139-02 |
|
![]() Previous |
![]() Next |
This chapter describes how to deploy a workbook that you have integrated with a Fusion web application to your end users once you have finalized the integration.
This chapter includes the following sections:
Section 14.1, "Introduction to Deploying Your Integrated Excel Workbook"
Section 14.2, "Making the Oracle ADF Desktop Integration Client Framework Available to End Users"
Section 14.5, "Deploying a Published Workbook with Your Fusion Web Application"
Section 14.6, "Passing Parameter Values from a Fusion Web Application Page to a Workbook"
Once you finish development of your integrated Excel workbook, you make the final integrated Excel workbook available to end users by deploying the resulting Fusion web application to an application server. Before you deploy a finalized Excel workbook that integrates with the Fusion web application, you must publish it as described in Section 14.4, "Publishing Your Integrated Excel Workbook". Once you have published the Excel workbook, you can deploy it using one of the methods outlined in the "Deploying Fusion Web Applications" chapter of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.
The end users that you deploy an integrated Excel workbook to must do the following:
Set up the Oracle ADF Desktop Integration client framework on their machines.
Make the Oracle ADF Desktop Integration client framework available to end users from, for example, a directory on your network. For more information, see Section 14.2, "Making the Oracle ADF Desktop Integration Client Framework Available to End Users".
Configure the security settings for their Excel application.
End users who want to use the functionality that you configure in an integrated Excel workbook must install the Oracle ADF Desktop Integration client framework. Store the tool (setup.exe
) that installs the Oracle ADF Desktop Integration client framework at a location where end users can download it. For example, you can make the setup.exe
tool available from a shared network location such as the following:
\\myFileServer\adfdi-deploy
Maintaining one shared network location makes it easier to manage the version of the Oracle ADF Desktop Integration client framework that end users install on their machines.
For information about using the setup.exe
tool, see Section 3.5, "Setting Up the Oracle ADF Desktop Integration Client Framework".
For more information about Microsoft ClickOnce installer, see the following:
End users who want to use integrated Excel workbooks must have their Excel application configured to allow it to run integrated Excel workbooks as described in Section 3.4, "Allowing Excel to Run an Integrated Excel Workbook". They also need to add the host name of the Fusion web application to the Excel application's list of trusted locations.
To add the host name of a Fusion web application to Excel's list of trusted locations:
Open Excel.
Click the Microsoft Office button and then click Excel Options.
Click the Trust Center tab and then click Trust Center Settings.
Click the Trusted Locations tab.
Select the Allow Trusted Locations on my network (not recommended) checkbox.
Click Add new location and enter the host name of the Fusion web application in the Path field of the dialog box that appears.
For example, you enter something similar to the following for the Master Price List module of the Fusion Order Demo application:
http://hostname:7101/FODMasterPriceList
Select the Subfolders of this location are also trusted checkbox.
Click OK.
Once you finalize configuring the Excel workbook with Oracle ADF functionality, you need to publish it. Publishing a workbook makes it available to the end users for whom you configured the integrated Excel workbook.
You publish a workbook by clicking a button on the Oracle ADF Desktop Designer toolbar and specifying values in the dialog boxes that appear.
To publish a workbook:
Before you start publishing an integrated Excel workbook, ensure that the ApplicationHomeFolder
and WebPagesFolder
properties in the Edit Workbook Properties dialog box are correct. If these properties are not set, the Oracle ADF Desktop Integration module prompts you to set them when you publish the integrated Excel workbook.
For more information, see Section 4.4.2, "How to Open an Excel Workbook for the First Time".
In the Oracle ADF Desktop Designer toolbar, click the Publish Workbook button.
Specify the directory and file name for the published workbook in the Publish Workbook dialog box that appears. The directory and file name that you specify for the published workbook must be different from the directory and file name for the design time workbook.
Click Save to save changes.
When you click the Publish button in design mode, the Oracle ADF Desktop Integration module triggers the following actions:
Prompts you to save any pending changes in the workbook
If you decline to save pending changes, the publication process is canceled. If you accept to save pending changes, the publication process proceeds.
Removes binding expressions that are visible in the worksheet while the workbook is in design mode
Changes the workbook mode to runtime mode
Removes the Oracle ADF Desktop Integration Designer toolbar and the Oracle ADF Desktop Integration Designer from Excel's Document Actions
Creates the published workbook with the file name you specified in the directory that you specified
Updates the client registry. For more information, see Section 11.3, "Checking the Integrity of an Integrated Excel Workbook's Metadata".
Add the integrated Excel workbook to the JDeveloper project for your Fusion web application if it is not already packaged with the other files that make up your JDeveloper project. This makes sure that the Excel workbooks you integrate with your Fusion web application get deployed when you deploy your finalized Fusion web application. For example, the Master Price List module stores the Excel workbooks that it integrates at the following location:
FOD_HOME\MasterPriceList\ViewController\public_html\excel
where FOD_HOME
is the installation directory for the Fusion Order Demo application.
Once 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 14-1 shows Internet Explorer's File Download dialog box, which was invoked by clicking the Excel > Edit Using Live Spreadsheet menu options on the PriceListSummary.jspx
page displayed by the Master Price List module.
To enable the functionality illustrated in Figure 14-1, the HTTP filter parameters for your Fusion web application must be configured to recognize Excel workbooks. JDeveloper automatically configures these parameters for you when you add Oracle ADF Desktop Integration to the technology scope of your Fusion web application, as explained in Section 4.2, "Adding Oracle ADF Desktop Integration to a Fusion Web Application". If you need to manually configure the HTTP filter parameters, see Appendix E, "Desktop Integration Settings in the Web Application Deployment Descriptor".
Once 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/EditPriceList.xlsx">Open the Master Price List in Excel</a>
where excel
is a subdirectory of the directory specified by the WebPagesFolder
workbook property and EditPriceList.xlsx
is the Excel workbook that the end user invokes.
Note: If you write the following HTML code to download the integrated Excel workbook, without first forward slash (/) in the path:
Internet Explorer displays a customization error when the end user downloads the integrated Excel workbook. |
You can provide functionality that allows end users to invoke Excel workbooks from buttons, lists and command menus. 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 in conjunction with a button to invoke an integrated Excel workbook.
Menu
Use the ADF Faces commandMenuItem
and fileDownloadActionListener
components.
The Edit Using Live Spreadsheet menu illustrated in Figure 14-1 uses the commandMenuItem
and fileDownloadActionListener
components. The PriceListSummary.jspx
page displays this menu. The following entries appear in the PriceListSummary.jspx
page of the Master Price List module with values configured for the commandMenuItem
and fileDownloadActionListerner
components:
<af:commandMenuItem textAndAccessKey="#{res['pls.productList.menu.lse.label']}" shortDesc="[Download a spreadsheet version of the pricelist application]" immediate="true" id="editDownLoadMenu"> <af:fileDownloadActionListener contentType="application/xls" filename="EditPriceList.xlsx" method="#{priceListSummaryBacking.downloadEditable}"/> </af:commandMenuItem>
For more information about creating web pages for a Fusion web application, see the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.
You can configure a page in your Fusion web application to pass parameter values to an integrated Excel workbook when an end user downloads the workbook from the page. For example, if an 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 will correspond 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.
To configure this functionality, you must:
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 add Oracle ADF Desktop Integration to the technology scope of your Oracle ADF Desktop Integration project. To verify the parameter values of the HTTP filter, see Section E.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 will download so that the workbook contains the parameters from the page in the Fusion web application from which the end invokes download.
You insert an <af:goLink>
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:goLink>
tag and its property values.
To configure the page in the Fusion web application:
In JDeveloper, insert the af:goLink
tag into the page from which the end user downloads the integrated Excel workbook.
In the Structure window, right-click the af:goLink node and choose Go to Properties.
Expand the Common section and set values for the properties described in the following table.
Property | Value |
---|---|
Text |
Write the text that appears to end users at runtime.
For example, write text such as the following to appear at runtime:
|
Destination |
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:
Note that the runtime URL-encoded value of the EL expression to the right of For example, the runtime URL-encoded value of 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. |
Optionally, expand the Behavior section and specify component IDs for the partialTriggers
property that, when invoked, update the values of the af:goLink
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
Save the page.
The following example shows the entries that JDeveloper generates in a JSF page using the examples in this procedure:
<af:goLink text="Download to Excel" destination="/excel/workbook.xlsx?productName=#{bindings.productName.attributeValue}" partialTriggers=":NextButton :PreviousButton :FirstButton :LastButton"/>
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.6.3, "How to Configure Properties in the Integrated Excel Workbook to Receive Parameters".
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.
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".
You configure the workbook Parameters
property and the worksheet Parameters
property so that the integrated Excel workbook that the end user downloads from the Fusion web application receives parameter values included in the query string of the workbook download URL.
To configure the workbook Parameters property:
Click Workbook Properties in the Oracle ADF Desktop Integration Designer.
Click the ellipsis button (...) beside the input field for Parameters to invoke the WorkbookParameter Collection Editor.
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:goLink
tag's Destination
property as described in Section 14.6.1, "How to Configure the Fusion Web Application's Page to Pass Parameters".
Repeat Step 3 as necessary to add other workbook initialization parameters.
Click OK.
For more information about the workbook Parameters
property, see Table A-18.
To configure the worksheet Parameters property:
Click Worksheet Properties in the Oracle ADF Desktop Integration Designer.
Click the ellipsis button (...) beside the input field for Parameters to invoke the WorksheetParameter Collection Editor.
Click Add to add a new worksheet parameter and configure it as in Figure 14-2:
(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.6.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.
productName
}
where productName
references the value of the Parameter
property you specified for the workbook initialization parameter.
Repeat Step 3 as necessary to add other workbook initialization parameters.
Click OK.
For more information about the worksheet Parameters
property, see Table A-19.
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:
Click Worksheet Properties in the Oracle ADF Desktop Integration Designer.
In the property inspector, set the value of SendParameters
as shown in the following table and Figure 14-2:
Set this property to... | This value... |
---|---|
SendParameters |
True to send workbook parameters when the workbook connects to the server in order to request metadata or data, each time it is opened. False is the default value.
For more information, see Section 15.3, "Restore Server Data Context Between Sessions". |
Click OK.
When the end user downloads the integrated Excel workbook from the Fusion web application, the af:goLink
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 will be sent when the workbook first connects to the server to request metadata or data, each time the workbook is opened.
To reset the initialization state for all worksheets in the workbook, invoke the ClearAllData
action. For more information about the ClearAllData
action, see Table A-17.