14 Deploying Your Integrated Excel Workbook

14.4.1 How to Publish an 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:

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

2. In the Oracle ADF Desktop Designer toolbar, click the Publish Workbook button.

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

4. Click Save to save changes.

14.4.2 What Happens When You Publish an Integrated Excel Workbook

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

14.6.1 How to Configure the Fusion Web Application's Page to Pass Parameters

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:

1. In JDeveloper, insert the af:goLink tag into the page from which the end user downloads the integrated Excel workbook.

2. In the Structure window, right-click the af:goLink node and choose Go to Properties.

3. 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: Download to Excel
   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: "/excel/workbook.xlsx?productName=#{bindings.productName.attributeValue}" Note that the runtime URL-encoded value of the EL expression to the right of ? must be less than 2048 bytes. If the runtime value exceeds 2048 bytes, the integrated Excel workbook downloads the URL arguments in the first 2048 bytes. Subsequent URL arguments do not get downloaded to the integrated Excel workbook. Instead, the Fusion web application writes log entries for these URL arguments identifying them as having not been downloaded. For example, the runtime URL-encoded value of productName=#{bindings.productName.attributeValue} must be less than 2048 bytes. 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: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

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

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

14.6.3 How to Configure Properties in the Integrated Excel Workbook to Receive Parameters

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:

1. Click Workbook Properties in the Oracle ADF Desktop Integration Designer.

2. Click the ellipsis button (...) beside the input field for Parameters to invoke the WorkbookParameter Collection Editor.

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

4. Repeat Step 3 as necessary to add other workbook initialization parameters.

5. Click OK.

   For more information about the workbook Parameters property, see Table A-18.

To configure the worksheet Parameters property:

1. Click Worksheet Properties in the Oracle ADF Desktop Integration Designer.

2. Click the ellipsis button (...) beside the input field for Parameters to invoke the WorksheetParameter Collection Editor.

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

   Figure 14-2 Worksheet Parameters

   
   

4. Repeat Step 3 as necessary to add other workbook initialization parameters.

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

1. Click Worksheet Properties in the Oracle ADF Desktop Integration Designer.

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

   
   

3. Click OK.

14.6.4 What Happens at Runtime When a Fusion Web Application Page Passes Parameters to an Integrated Excel Workbook

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.