7 Working with Oracle ADF Desktop Integration Table-type Components

7.4.1 How to Configure an ADF Table Component to Insert Data Using a View Object's Operations

If you want the changes that an end user makes in an ADF Table component to be committed once he or she invokes the ADF Table component's Upload action, you need to configure a number of the ADF Table component's properties.

To configure an ADF Table component to insert data using a view object's operations:

1. If not already 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".

2. Select the cell in the Excel worksheet that references the ADF Table component and click the property inspector button in the ­Oracle ADF Desktop Integration Designer toolbar to display the Edit Component: ADF Table dialog box.

3. Configure the RowActions properties of the ADF Table component as described in the following table.

   Set this property to...	This value...
   InsertRowEnabled	True
   InsertBeforeRowActionID	The CreateInsert action binding that the page definition file exposes.

   
   

4. Configure the BatchOptions properties of the ADF Table component as described in the following table.

   Set this property to...	This value...
   CommitBatchActionID	The Commit action binding that the page definition file exposes.

   
   

5. Configure the Columns property of the ADF Table component as described in the following table.

   Set this property to...	This value...
   InsertUsesUpdate	True
   UpdateComponent	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 Oracle 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 do not need to modify.
   CellStyleName	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".
   HeaderLabel	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".
   HeaderStyleName	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".

   
   

6. Repeat Step 5 for each column that contains data that you want to commit during invocation of the Upload action.

   For information about ADF Table component properties, see Appendix A, "ADF Table Component Properties and Actions".

7.4.2 What Happens at Runtime When an ADF Table Component Inserts Data Using a View Object's Operations

During invocation of the ADF Table component's Upload action, the Oracle ADF Desktop Integration module does the following for each newly inserted row:

1. Invokes the action binding specified by the ADF Table component's RowActions.InsertBeforeRowActionID property if an action binding is specified for this property.

   For example, the procedure in Section 7.4.1, "How to Configure an ADF Table Component to Insert Data Using a View Object's Operations" specifies the CreateInsert action binding as the value for the RowActions.InsertBeforeRowActionID property.

2. Sets values for each attribute binding according to the specified action binding.

3. Invokes the action binding specified by the ADF Table component's RowActions.InsertAfterRowActionID property if an action binding is specified for this property.

   The procedure in Section 7.4.1, "How to Configure an ADF Table Component to Insert Data Using a View Object's Operations" does not specify a value for the RowActions.InsertAfterRowActionID property.

For more information about built-in operations, see the "What Happens When You Use Built-in Operations to Change Data" section in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

7.5.1 How to Configure a Worksheet to Download Data to an ADF Table Component

Configure an Oracle ADF component, a worksheet menu item, or a worksheet event to invoke an action set that, in turn, invokes the ADF Table component Download action.

To configure a worksheet to download data to an ADF Table component:

1. Open the Action Collection Editor to configure an action set for the worksheet event, worksheet menu item, or Oracle ADF component that is going to invoke the action set at runtime.

   For more information about invoking action sets, see Section 8.2, "Using Action Sets".

2. Add the ADF Table component Download action to the list of actions that the action set invokes at runtime.

   The ADF Table component Download action downloads the current state of the binding referenced by the ADF Table component TreeID property. To make sure that the state of this binding is up to date prior to download, add a query action that refreshes the binding before the action set invokes the ADF Table component Download action.

   Figure 7-3 shows the Action Collection Editor in the EditPriceList.xlsx workbook where the action set invoked by the worksheet event Startup is configured.

   Figure 7-3 Action Set Downloading Data to an ADF Table Component

   
   

3. Click OK.

7.5.2 What Happens at Runtime When an 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. This action downloads the current state of the binding referenced by the ADF Table component TreeID property. If the tree binding referenced by the TreeID property contains data with a master-detail relationship (for example, a product category with multiple products), the ADF Table component shows the first record in the detail result set (for example, the first product). How you configured the tree binding in the Fusion web application determines which of the detail records is defined as the first record. For more information about using tree bindings to display master-detail data, see the "Using Trees to Display Master-Detail Objects" section in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

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.13, "Limiting the Number of Rows Your Table-type Component Downloads".

7.6.1 How to Configure a Worksheet to Download Pre-Insert Data to an ADF Table Component

Configure an Oracle ADF component, a worksheet menu item, or a worksheet event to invoke an action set that, in turn, invokes the ADF Table component DownloadForInsert action.

To configure a worksheet to download pre-insert data to an ADF Table component:

1. Open the Action Collection Editor to configure an action set for the worksheet event, worksheet menu item, or Oracle ADF component that is going to invoke the action set at runtime.

   For more information about invoking action sets, see Section 8.2, "Using Action Sets".

2. Add the ADF Table component DownloadForInsert action to the list of actions that the action set invokes at runtime.

3. Click OK.

7.6.2 What Happens at Runtime When an ADF Table Component Downloads Pre-Insert 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 DownloadForInsert action of the ADF Table component. This action downloads pre-insert data from the Fusion web application and inserts it in rows of the ADF Table component in the Excel worksheet. The InsertComponent property is configured for the ADF Table component columns associated with the rows inserted to host the pre-insert data. End users can invoke the ADF Table component's Upload action to commit the pre-insert data to the Fusion web application's database.

7.7.1 How to Configure a Worksheet to Upload Data from an ADF Table Component

Configure an Oracle ADF component, a worksheet menu item, or a worksheet event to invoke an action set that, in turn, invokes the ADF Table component Upload action.

To configure a worksheet to upload changed data from an ADF Table component:

1. Open the Action Collection Editor 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".

2. Add the ADF Table component Upload action to the list of actions that the action set invokes at runtime.

   Figure 7-4 shows the Action Collection Editor in the EditPriceList.xlsx workbook where the action set invoked by the ADF Button labeled Save Changes at runtime is configured.

   Figure 7-4 Action Set Uploading Data from an ADF Table Component

   
   

3. Click OK.

7.7.2 What Happens at Runtime When an ADF Table Component Uploads Data

At runtime, the end user invokes the action set through whatever mechanism you configured (ADF component, worksheet menu item, worksheet event). This triggers the following sequence of events:

1. If the ADF Table component contains dynamic columns, the Oracle ADF Desktop Integration module checks that dynamic columns expanded the last time the ADF Table component's Download action was invoked are still present in the Fusion web application. If they are not present in the Fusion web application, the Oracle ADF Desktop Integration module prompts the end user to determine if the end user wants to continue to upload. If the end user decides not to continue, the Oracle ADF Desktop Integration module returns a failure code to the executing action set.

2. If the ADF Table component contains no pending changes to upload, the ADF Table component's Upload action returns a success code.

3. If you did not configure a custom upload dialog for the action set, as described in Section 7.7.3, "How to Create a Custom Upload Dialog", the Oracle ADF Desktop Integration module presents a default upload dialog box shown in Figure 7-5.

   Figure 7-5 Default Upload Dialog Box

   
   

4. If the end user clicks Cancel, the Oracle ADF Desktop Integration module returns a failure 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.

5. The ADF Table component uploads data based on the values specified for the BatchOptions group of properties. For more information about batch options for the ADF Table component, see Section 7.9, "Batch Processing in an ADF Table Component".

6. If the ADF Table component uploads all batches successfully, the ADF Table component then downloads all rows from the Fusion web application if the end user selected this option in Step 4.

7. 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. The Oracle ADF Desktop Integration module returns a failure code to the action set.

8. If an error occurs during execution of the action set, the Oracle ADF Desktop Integration module returns an error code to the action set.

If you configured a status message as described in Section 8.2.5, "How to Display a Status Message While an Action Set Executes", a status message appears while the action set executes. Once the action set completes execution, an alert message appears if you configured one as described in Section 8.2.7, "How to Provide an Alert After the Invocation of an Action Set".

7.7.3 How to Create a Custom Upload Dialog

You display a page from Fusion web application that offers end users different options to those presented in the default upload dialog box. You add a Dialog action before the action that invokes the ADF Table component's Upload action in the action set.

To create a custom upload dialog:

1. Create a page in the JDeveloper project where you develop the Fusion web application. For information on how to create this page, see Section 8.4, "Displaying Web Pages from a Fusion Web Application".

2. In addition to the ADFdi_CloseWindow 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 span elements described in the following table:

   Name	Description
   ADFdi_AbortUploadOnFailure	If you set this span element to True, the action set stops uploading if it encounters a failure. If the span element references False, the action set attempts to upload all rows and indicates if each row succeeded or failed to upload. The default value for this span element is True.
   ADFdi_DownLoadAfterUpload	Set this span 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. The default value for this span element is False.

   
   

   Note:

   The page you create must include both span elements if you want to prevent the Oracle ADF Desktop Integration module presenting the default upload dialog box 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.7.4 What Happens at Runtime When a Custom Upload Dialog Appears

The page from the Fusion web application that you configure the Dialog action in the action set to display appears instead of the default upload dialog box. 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.7.2, "What Happens at Runtime When an ADF Table Component Uploads Data".

7.8.1 How to Configure an ADF Table Component to Delete Rows in the Fusion Web Application

Configure an action set to invoke a Delete action binding in the page definition file that is associated with the worksheet that hosts the ADF Table component and set values for a number of RowActions properties.

To configure an ADF Table component to delete rows in a Fusion web application:

1. If not already 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".

2. Open the property inspector for the ADF Table component and set values for the RowActions group of properties as described in the following table.

   Set this property...	To...
   DeleteRowActionID	The Delete action binding that the page definition file exposes.
   DeleteRowEnabled	True to enable the ADF Table component to delete rows in the Fusion web application. False is the default value.

   
   

   For more information about ADF Table component properties, see Section A.8, "ADF Table Component Properties and Actions".

3. Click OK.

4. Open the Action Collection Editor to configure an action set for the Oracle ADF component, worksheet menu item, or worksheet event that the end user uses to invoke the action set at runtime.

5. Add the ADF Table component's DeleteFlaggedRows action to the list of actions that the action set invokes at runtime.

   For more information about invoking action sets, see Section 8.2, "Using Action Sets".

6. Click OK.

7.8.2 What Happen at Runtime When an ADF Table Component Deletes Rows in a Fusion Web Application

The end user flags rows to delete as described in Section 7.9.2, "Row Flagging in an ADF Table Component". He or she then invokes the action set. The following sequence of events occur:

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

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.

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

6. If an unexpected exception occurs while the action set invokes its actions, an error code is returned to the action set.

7.9.1 Configuring Batch Options for an ADF Table Component

The ADF Table component has a group of properties (BatchOptions) that allow you to configure how the ADF Table component manages batches of rows. Information about these properties can be found in Appendix A, "ADF Table Component Properties and Actions".

To configure batch options for an ADF Table component:

1. Select the cell in the Excel worksheet that references the ADF Table component and then click the property inspector button in the Oracle ADF Desktop Integration Designer toolbar.

2. Set values for the BatchOptions group of properties in the property inspector that appears.

   Set this property...	To...
   BatchSize	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.
   CommitBatchActionID	The action binding to invoke once the ADF Table component processes each batch. Typically, this is the Commit action binding.
   LimitBatchSize	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.
   StartBatchActionID	Specify the action binding to invoke at the beginning of each batch.

   
   

3. Click OK.

7.9.2 Row Flagging in an ADF Table Component

By default, the ADF Table component includes a column, _ADF_FlagColumn, that facilitates the selection of rows for flagged-row processing. One of the following actions by an end user in a cell of the _ADF_FlagColumn column flags the corresponding row for processing by actions invoked by a component action:

• Double-click a cell

• Type a character in a cell

When an end user carries out one of the previously listed actions, an arrow that points to the right appears (or is cleared if already flagged) in the cell to indicate that the row is flagged. Figure 7-6 shows an example.

Figure 7-6 Flagged Column in an ADF Table Component

The following component actions can be invoked on flagged rows:

• DeleteFlaggedRows

• DownloadFlaggedRows

• FlagAllRows

• UnflagAllRows

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 Appendix A, "ADF Table Component Actions".

At runtime, an end user can invoke one 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".

7.12.1 How to Insert an ADF Read-only Table Component

You use the Oracle ADF Desktop Integration Designer to insert an ADF Read-only Table component into a worksheet.

To insert an ADF Read-only Table component:

1. Select the cell in the Excel worksheet where you want to anchor the component.

2. In the bindings palette, select the binding that you want to use to create the ADF Read-only Table component.

3. In the dialog box that appears, select ADF Read-only Table.

   Note:

   You can also insert an ADF Read-only Table component by using the components palette. Select ADF Read-only Table and click Insert Component. If you use the components palette to create the component, you have to add each column that you want to appear in the component at runtime.

4. Configure properties in the property inspector that appears to determine the columns to appear and the actions the component invokes at runtime.

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.

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

To manually add a column to the ADF Read-only Table component:

1. Select the cell in the worksheet that hosts the ADF Read-only Table component and click the property inspector button in the Oracle ADF Desktop Integration Designer toolbar to display the Edit Component: ADF Read-only Table dialog box.

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

3. Click Add to add a new column to the ADF Read-only Table component.

4. Set values for the properties of the new column.

   For information about the properties of an ADF Read-only Table component column, see Table A-12.

5. Click OK.

7.13.1 How to Limit the Number of Rows a Component Downloads

Specify the number of rows that you want the component to download when it invokes its Download action as a value for the RowLimit.MaxRows property. Optionally, write an EL expression for the RowLimit.WarningMessage property so that the end user receives a message if the number of rows available to download exceeds the number specified by RowLimit.MaxRows.

To limit the number of rows a table-type component downloads:

1. Select the cell in the Excel worksheet that references the table-type component and click the property inspector button in the Oracle ADF Desktop Integration Designer toolbar.

   For more information, see Section 8.2, "Using Action Sets".

2. Configure properties for the RowLimit group of properties as described in the following table. For more information about these properties, see Section A.1, "Frequently Used Properties in the Oracle ADF Desktop Integration Module".

   Set this property to...	This value...
   RowLimit.Enabled	Set to True to limit the number of rows downloaded to the value specified by RowLimit.MaxRows.
   RowLimit.MaxRows	Specify an EL expression that evaluates to the maximum number of rows to download.
   RowLimit.WarningMessage	Write an EL expression for this property if you want 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. The default value also generates a message: #{_ADFDIres['ROWLIMIT_WARNINGS_MESSAGE_1']} If the value for this property is null, the Download action downloads the number of rows specified by RowLimit.MaxRows without displaying a message to the end user.

   
   

3. Click OK.

7.13.2 What Happens at Runtime When You Limit the Number of Rows a Component Downloads

When invoked, the Table-type component's Download action downloads the number of rows that you specified as the value for RowLimit.MaxRows from the Fusion web application. A message dialog similar to the one in Figure 7-11 appears if you specify an EL expression for RowLimit.MaxRows or do not modify its default value:

#{_ADFDIres['ROWLIMIT_WARNINGS_MESSAGE_1']}

Figure 7-11 Row Limit Exceeded Warning Message

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

To clear the values of cached attributes in an ADF Table component:

1. Open the Action Collection Editor for the Oracle ADF component that is going to invoke the DoubleClickActionSet at runtime.

   For more information about invoking action sets, see Chapter 8, "Using Action Sets".

2. Add an action to the DoubleClickActionSet that invokes the ADF Table component's ClearCachedRowAttributes action.

3. Click OK.

7.14.2 What Happens at Runtime When 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 RowData.CachedAttributes property for the current row of the ADF Table component.