Fusion Middleware Documentation
Advanced Search


Developing Applications with Oracle ADF Desktop Integration

A ADF Desktop Integration Component Properties and Actions

This appendix lists and describes the properties of ADF Desktop Integration components. It also describes the actions that certain components (such as ADF Input Text, ADF Output Text, ADF List of Values, ADF Button, ADF Table, Workbook, and Worksheet) expose.

This appendix includes the following sections:

A.1 Frequently Used Properties in the ADF Desktop Integration

Table A-1 lists alphabetically properties in ­ADF Desktop Integration that many components reference.

Table A-1 Frequently Used Properties in ADF Desktop Integration

Name Type EL Description

ActionSet

 

N

For information about action sets, see Section A.11, "Action Set Properties."

Annotation

String

N

Use this field to enter a comment about the component's use in the worksheet. Comments you enter have no effect on the behavior of the workbook. They are the equivalent of code comments.

ComponentID

String

N

ADF Desktop Integration generates this string to uniquely identify each instance of an ADF component in an integrated Excel workbook.

Label

String

Y

Specify an EL expression that is evaluated at runtime. For information about EL expressions in ADF Desktop Integration, see Appendix B, "ADF Desktop Integration EL Expressions." For information about using labels, see Section 9.4, "Using Labels in an Integrated Excel Workbook."

Position

 

N

This property defines the upper-left corner of the Oracle ADF component in the integrated Excel workbook.

ReadOnly

Boolean

Y

Set this property to TRUE so that ADF Desktop Integration ignores changes a user makes to a cell that references a component which uses this property. This property is independent of Excel's workbook and worksheet protection functionality. Setting ReadOnly to TRUE does not prevent a user from modifying a cell. When TRUE, the behavior for cells that reference Oracle ADF components is as follows:

  • ADF Desktop Integration overwrites changes without warning when a worksheet is refreshed.

  • No changes are sent to the Fusion web application when the integrated Excel workbook is synchronized with the Fusion web application.

To avoid end user confusion, apply styles to the cells where you set ReadOnly to TRUE that provide a visual clue to users that they cannot modify the cell's contents. For information about applying styles, see Section 9.2, "Working with Styles."

You can also use the Worksheet Protection feature of ADF Desktop Integration to prevent editing of locked cells at runtime. For more information, see Section 9.7, "Using Worksheet Protection."

Setting the ReadOnly property to True for an ADF List of Values component, a TreeNodeList subcomponent, or a ModelDrivenColumn component which renders a list binding may confuse end users. To avoid any confusion, consider using an ADF Output Text component or subcomponent.

StyleName

String

Y

Specifies the style in the current Excel workbook to apply when the Oracle ADF component is rendered. For more information, see Section 9.2, "Working with Styles."

Value

Varies

Y

This property references an EL expression that is evaluated after the invocation of the ADF Table component's RowDownSync action or a worksheet's DownSync action. The resulting value is typically the primary value seen in the selected component.


Many label-type properties are optional and default to empty. At runtime, if the value of the property is empty, ADF Desktop Integration provides a default, localized value. If you want the value of the property to appear as empty, set its value to a single space character, or provide an EL expression that evaluates to an empty string.

A.2 ADF Input Text Component Properties

Table A-2 lists alphabetically the properties of the ADF Input Text component.

Table A-2 ADF Input Text Component Properties

Name Description

Annotation

For information about this property, see Table A-1.

ComponentID

For information about this property, see Table A-1.

InputText.DoubleClickActionSet

Specifies the action set invoked when a user double-clicks the cell. For information about action sets, see Section A.11, "Action Set Properties."

InputText.ReadOnly

For information about this property, see Table A-1.

InputText.Value

For information about this property, see Table A-1.

Position

For information about this property, see Table A-1.

StyleName

For information about this property, see Table A-1.


A.3 ADF Output Text Component Properties

Table A-3 lists alphabetically the properties of the ADF Output Text component.

Table A-3 ADF Output Text Component Properties

Name Description

Annotation

For information about this property, see Table A-1.

ComponentID

For information about this property, see Table A-1.

OutputText.DoubleClickActionSet

Specifies the action set invoked when a user double-clicks the cell. For information about action sets, see Section A.11, "Action Set Properties."

OutputText.Value

For information about this property, see Table A-1.

Position

For information about this property, see Table A-1.

StyleName

For information about this property, see Table A-1.


A.4 ADF Label Component Properties

The ADF Label component displays a static string value at runtime. ADF Desktop Integration generates the value when the EL expression that the Label property references is evaluated. For information about using labels, see Section 9.4, "Using Labels in an Integrated Excel Workbook."

Table A-4 lists alphabetically the properties that the ADF Label component references.

Table A-4 ADF Label Component Properties

Name Description

Annotation

For information about this property, see Table A-1.

ComponentID

For information about this property, see Table A-1.

Label

For information about this property, see Table A-1.

Position

For information about this property, see Table A-1.

StyleName

For information about this property, see Table A-1.


A.5 ADF List of Values Component Properties

Table A-5 lists the properties of the ADF List of Values component. For information about creating an ADF List of Values component, see Section 6.6, "Inserting an ADF List of Values Component."

Table A-5 ADF List of Values Component Properties

Name Type EL Description

Annotation

   

For information about this property, see Table A-1.

ComponentID

   

For information about this property, see Table A-1.

ListOfValues.DependsOnListID

List binding

N

Select the list binding whose value at runtime determines the choices available in the dependent list of values at runtime.

The list binding that you select can be a model-driven list.

For more information about dependent list of values, see Section 8.8, "Creating Dependent Lists of Values in an Integrated Excel Workbook."

ListOfValues.ListID

List binding

N

Select the list binding that defines the values available in the list of values. The list binding that you select can be a model-driven list.

ListOfValues.ReadOnly

Boolean

N

For information about this property, see Table A-1.

Position

   

For information about this property, see Table A-1.

StyleName

   

For information about this property, see Table A-1.


A.6 TreeNodeList Subcomponent Properties

The TreeNodeList is an ADF Table subcomponent that renders dropdown menus in columns of the ADF Table component at runtime. It provides the same functionality to end users as the ADF List of Values component.

The TreeNodeList subcomponent does not appear in the components palette of the ADF Desktop Integration task pane. Instead, you configure properties for this subcomponent when you specify TreeNodeList as the subcomponent to invoke for the ADF Table component's UpdateComponent or InsertComponent table column properties described in Section A.9.2, "ADF Table Component Column Properties."

Table A-6 describes the properties that you configure for the TreeNodeList subcomponent.

Table A-6 TreeNodeList Subcomponent Properties

Name Type EL Description

DependsOnList

Tree binding attribute or List binding

Y

Specify the tree binding attribute or list binding that serves as the parent list of values in a dependent list of values.

Note that the tree binding attribute you specify must be associated with a model-driven list.

For more information about dependent list of values, see Section 8.8, "Creating Dependent Lists of Values in an Integrated Excel Workbook."

List

Tree binding attribute

Y

Specify the tree binding attribute associated with a model-driven list that defines the values available in the runtime dropdown menu to appear in the ADF Table component's column.

ReadOnly

Boolean

Y

For information about this property, see Table A-1.


A.7 ModelDrivenColumnComponent Subcomponent Properties

The ModelDrivenColumnComponent subcomponent, like the TreeNodeList subcomponent, does not appear in the components palette of the ADF Desktop Integration task pane. Instead, you configure properties for this subcomponent when you specify ModelDrivenColumnComponent as the subcomponent to invoke for the ADF Table component's UpdateComponent or InsertComponent table column properties described in Section A.9.2, "ADF Table Component Column Properties."

Table A-7 describes the properties that you configure for the ModelDrivenColumnComponent subcomponent.

Table A-7 ModelDrivenColumnComponent Subcomponent Properties

Name Type EL Description

DoubleClickActionSet

   

Specifies the action set invoked when a user double-clicks the cell. For information about action sets, see Section A.11, "Action Set Properties."

ReadOnly

Boolean

Y

For information about this property, see Table A-1.

Value

Varies

Y

For information about this property, see Table A-1.


A.8 ADF Button Component Properties

Table A-8 lists alphabetically the properties of the ADF Button component.

Table A-8 ADF Button Component Properties

Name Description

Annotation

For information about this property, see Table A-1.

ClickActionSet

Specify the action set to invoke when a user clicks the button. For information about action sets, see Section A.11, "Action Set Properties."

ComponentID

For information about this property, see Table A-1.

Label

For information about this property, see Table A-1.

LowerRightCorner

This property is an Excel cell reference. Used with Position, it specifies the area that the button occupies on the Excel worksheet.

Position

For information about this property, see Table A-1.


A.9 ADF Table Component Properties and Actions

The ADF Table component uses the properties and component actions listed here.

A.9.1 ADF Table Component Properties

Table A-9 lists alphabetically the properties the ADF Table component uses.

Table A-9 ADF Table Component Properties

Name Type EL Description

Annotation

   

For information about this property, see Table A-1.

BatchOptions

   

This group of properties enables you to configure batch options for the ADF Table component. For more information about how you use these properties, see Section 7.11, "Batch Processing in an ADF Table Component."

BatchOptions.BatchSize

Integer

N

Specifies how many rows to process before an ADF Table component action (Upload or DeleteFlaggedRows) invokes CommitBatchActionID. Any value other than a positive integer results in all rows being processed in a single batch. The default value is 100 rows.

A value for this property is required.

BatchOptions.CommitBatchActionID

Action binding

N

Specify an action binding to invoke when the number of rows specified by BatchSize have been processed. The action binding is expected to be a commit-type action.

BatchOptions.LimitBatchSize

Boolean

N

Set this property to TRUE to process rows in batches where each batch contains the number of rows specified by BatchSize. If set to FALSE, all rows are processed in a single batch.

BatchOptions.StartBatchActionID

Action binding

N

Specify an action binding to invoke at the beginning of each batch. For example, this property might be used for an operation like "start transaction", if required by a particular database.

A value for this property is optional.

Columns

   

An array of columns. For information about the properties that each column in the array supports, see Section A.9.2, "ADF Table Component Column Properties."

ComponentID

   

For information about this property, see Table A-1.

Position

   

For information about this property, see Table A-1.

RowActions

   

This group of properties allows you specify which actions are enabled and can be invoked.

RowActions.DeleteRowActionID

Action binding

N

Specify an action binding to invoke for each row flagged for deletion.

A value for this property is optional.

RowActions.DeleteRowEnabled

Boolean

N

Set to TRUE to allow a user to delete existing rows. FALSE is the default value.

A value for this property is required.

RowActions.FailureActionID

Action binding

N

Specify an action binding to invoke if failures occur during the processing of rows.

A value for this property is optional.

RowActions.InsertAfterRowActionID

Action binding

N

Specify an action binding to invoke for each row inserted using the ADF Table component Upload action. The action binding is invoked after the attributes are set. Use of this property is suitable with a custom action where a variable iterator is employed along with the main iterator.

A value for this property is optional.

RowActions.InsertBeforeRowActionID

Action binding

N

Specify an action binding to invoke for each row inserted using the Upload component action. The action binding specified is invoked before the attributes are set.

A value for this property is optional.

RowActions.InsertRowEnabled

Boolean

N

Set to TRUE to allow the end user insert new rows in the ADF Table component. FALSE is the default value.

If you set this property to TRUE, you must specify values for one or both of the following properties:

  • RowActions.InsertAfterRowActionID

  • RowActions.InsertBeforeRowActionID

Which property (InsertAfterRowActionID or InsertBeforeRowActionID) you specify a value for depends on how your Fusion web application creates new rows. Typically, a Fusion web application uses the CreateInsert action binding to create and insert a new row. In this scenario, you specify the CreateInsert action binding as the value for InsertBeforeRowActionID.

For more information about inserting rows in an ADF Table component, see Section 7.7, "Configuring an ADF Table Component to Insert Data."

RowActions.InsertRowsAfterUploadEnabled

Boolean

N

Set to TRUE to allow the end user to reinsert changed rows regardless of whether they have been previously uploaded. FALSE is the default value.

The property is ignored if InsertRowEnabled is set to FALSE.

RowActions.UpdateRowActionID

Action binding

N

Specify an action binding to invoke for each row updated.

A value for this property is optional.

RowActions.UpdateRowEnabled

Boolean

N

Set to TRUE to allow a user update an existing row. TRUE is the default value.

A value for this property is required.

RowData

   

Set values for the CachedAttributes property when you want to cache data in an integrated Excel workbook across multiple sessions with the Fusion web application.

Set a value for the ChangeIndicatorAttributeID property to determine whether a row has been modified by another user since you downloaded it from the Fusion web application.

RowData.CachedAttributes

Array

N

Specify values for the properties in this array to determine the attributes for which data is cached. Each CachedTreeAttribute element in this array supports the following properties:

  • Value

    Select the tree binding attribute for which data is to be cached.

  • Annotation

    For more information about this property, see Table A-1.

Do not configure a component (for example, an ADF Table component's column or an ADF Input Text component) so the end user can view or edit an attribute binding that you have also specified for an element in the RowData.CachedAttributes array. The RowData.CachedAttributes array caches the values retrieved by the worksheet DownSync action. The worksheet UpSync action sends the values cached by the RowData.CachedAttributes array to the Fusion web application. This may override edits the end user makes to an attribute binding exposed through a component in the worksheet.

For information about using the RowData.CachedAttributes array to cache data in an ADF Table component, see Section 8.5, "Adding a Custom Popup Picker Dialog to an ADF Table Column."

RowData.ChangeIndicatorAttributeID

Attribute Binding

Y

Specify an EL expression that evaluates to a row-specific tree attribute binding value. The attribute value is used to determine if a row has been modified by another user since the row was last downloaded to your integrated Excel workbook.

For more information, see Section 12.7, "Handling Data Conflicts When Uploading Data from a Workbook."

RowLimit

   

This group of properties allows you configure the number of rows that the ADF Table component or ADF Read-only Table component download and display.

For more information, see Section 7.18, "Limiting the Number of Rows Your Table-Type Component Downloads."

RowLimit.Enabled

Boolean

N

Set to TRUE to limit the number of rows downloaded to the value specified by RowLimit.MaxRows. TRUE is the default value.

A value for this property is required.

RowLimit.MaxRows

Integer

Y

Specify an EL expression that evaluates to the maximum number of rows to download. The component evaluates the EL expression when it invokes its Download action. The default value is 500. If MaxRows is not a positive integer, the component attempts to download as many rows as possible. An invalid expression such as "ABC" is interpreted as -1 (negative integer). As a result, the component attempts to download as many rows as possible.

Note that setting the value of MaxRows to 0 results in a message where the user is asked if they want to download the first 0 rows. To avoid this, set MaxRows to a positive integer other than 0.

RowLimit.WarningMessage

String

Y

(Optional) Write an EL expression 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. This expression is evaluated each time the Table's Download action is invoked. The maximum number of rows that a Excel 2007, or a higher version, worksheet can contain is approximately 1 million. If this property is left blank, ADF Desktop Integration displays a message similar to "Too many rows available. Do you want to download the first {0} rows?" that is translated for the current culture settings.

You can specify a string key from a custom resource bundle to use, instead of the default value. If desired, you may supply a custom message to replace the default one. Any custom message must contain {0}. {0} will be replaced by the MaxRows value.

For more information about resource bundles, see Section 10.2, "Using Resource Bundles in an Integrated Excel Workbook."

TreeID

Binding

N

Specify a tree binding from the current worksheet's page definition file. You must specify a value for this property so that row downloads and uploads function properly. For more information about the page definition requirements for an integrated Excel workbook, see Table 4-1.

UniqueAttribute

Attribute binding

Y

Specify an EL expression that evaluates to a unique row-specific tree attribute binding value. The value of this attribute is cached in the integrated Excel workbook during the ADF Table component's Download action. ADF Desktop Integration uses this value to ensure that the tree binding's iterator is positioned correctly before setting or getting data for a given ADF Table component row.

Note that this value is required only when the underlying tree binding iterator does not expose a rowKey.

This value is optional when:

  • The tree binding iterator exposes a rowKey, in which case the rowKey value is used for positioning

    OR

  • The ADF Table component is configured to be insert-only (RowActions.InsertRowEnabled is set to True and RowActions.UpdateRowEnabled is set False)


A.9.2 ADF Table Component Column Properties

Table A-10 describes the properties that a column in the TableColumn array can use.

Table A-10 ADF Table Component Column Properties

Name Type EL Description

Annotation

   

For information about this property, see Table A-1.

CellStyleName

String

Y

Write an EL expression that resolves to an Excel style name that is applied to each cell in the column.

DynamicColumn

Boolean

N

Set to True to make a column dynamic. False is the default value. For more information about dynamic columns, see Section 7.16, "Adding a Dynamic Column to Your ADF Table Component."

HeaderLabel

String

Y

Write an EL expression that, when evaluated at runtime, displays a label in the column header.

HeaderStyleName

String

Y

Write an EL expression that resolves to an Excel style name that is applied to each cell in the column header.

ID

String

N

Assign a name to the column to identify it and its purpose. The value that you assign for this property has no functional impact. However, you must specify a value and the value that you specify must be unique within the list of columns. It serves to help you keep track of columns in the ADF Table component. The following IDs are reserved to the three default columns in the ADF Table component:

  • _ADF_ChangedColumn

  • _ADF_FlagColumn

  • _ADF_StatusColumn

For more information about these columns, see Section 7.12, "Special Columns in the ADF Table Component."

InsertComponent

ADF component

N

Specifies the properties of the component that represents the binding for insert operations. This component can be one of the following:

When InsertUsesUpdate is set to True, the ADF Table component ignores the value of the InsertComponent property.

InsertUsesUpdate

Boolean

N

Set to True if insert and update operations use the same component type. When True, the ADF Table component ignores the values of the InsertComponent property and reads the value of the UpdateComponent property.

The default value is True.

UpdateComponent

ADF component

N

Specifies the properties of the component that represents the binding for update and download operations. This component can be one of the following:

Visible

Boolean

Y

Write an EL expression that resolves to True or False. If True, the column appears in the ADF Table component. If False, the column does not appear. True is the default value.

If you make a column dynamic, the ADF Table component ignores the value of the Visible property. For more information about dynamic columns, see Section 7.16, "Adding a Dynamic Column to Your ADF Table Component."


A.9.3 ADF Table Component Actions

Table A-11 describes the component actions available for use with the ADF Table component.

Table A-11 ADF Table Component Actions

Component Action Description

ClearCachedRowAttributes

Clears the values of cached attributes for the current row of the ADF Table component. Only a DoubleClickActionSet in an ADF Table component's column should invoke this action.

DeleteFlaggedRows

Invokes a specified action on each of a set of flagged rows in the ADF Table component and then removes these rows from the ADF Table component.

For more information, see Section 7.10, "Configuring an ADF Table Component to Delete Rows in the Fusion Web Application."

DisplayRowErrors

Displays error details for the current row in the ADF Table component if error details are available. This action should only be invoked from a column's action set in an ADF Table component. By default, the _ADF_StatusColumn described in Table 7-8 is configured with an action set that invokes this action.

DisplayTableErrors

Displays a detailed list of errors in a message dialog for the ADF Table component if any errors are available. Do not invoke this action from a column's action set in an ADF Table component. Instead configure an action set for an ADF Button, ADF Output Text component, or worksheet ribbon button to invoke this action.

Download

Download the rows corresponding to the current state of TreeID. For information about TreeID, see Section A.9.1, "ADF Table Component Properties."

DownloadFlaggedRows

Downloads the flagged rows from the tree binding specified by TreeID. For information about TreeID, see Table A-9.

This action applies to the downloaded rows only, and inserted rows are ignored.

DownloadForInsert

This action is obsolete. For more information, see Section 7.4, "Configuring Oracle ADF Component to Download Data to an ADF Table Component."

FlagAllRows

Sets the flag for all rows.

Invoke this action to set a flag character in all rows of the _ADF_FlagColumn column. The flag character has the following properties:

Character Code 25CF, Unicode(hex)

It appears as a solid circle.

For more information about the _ADF_FlagColumn column, see Section 7.11.2, "Row Flagging in an ADF Table Component" and Section 7.12, "Special Columns in the ADF Table Component."

Initialize

This action performs the following actions:

  • Removes all rows of data from the ADF Table component

  • Clears the values of cached attributes from rows in the ADF Table component

  • Creates the placeholder row

  • Recalculates how many dynamic columns to render in the ADF Table component

  • Redraws column headers

If the ADF Table component contains pending changes that have not been saved in the integrated Excel workbook, a dialog appears to the end user that allows cancellation of invocation of this action.

MarkAllRowsChanged

Specify this component action to mark all rows in the table as changed in _ADF_ChangeColumn.

MarkAllRowsUnchanged

Specify this component action to clear all flags from the _ADF_ChangedColumn column.

RowDownSync

Synchronizes data from the row in the ADF Table component's iterator in the Fusion web application that corresponds to the current worksheet row to the worksheet. As this action acts upon the current worksheet row, only a DoubleClickActionSet associated with a column in the ADF Table component should invoke this action.

The ADF Table component does not evaluate or apply the value of a column's Visible property when invoking RowDownSync. The ADF Table component evaluates and applies the value of a column's CellStyleName property when invoking RowDownSync. For more information about column properties, see Section A.9.2, "ADF Table Component Column Properties."

RowUpSync

Synchronizes any pending changes in the current worksheet row that the ADF Table component references to the Fusion web application. RowUpSync acts upon the current worksheet row so only a DoubleClickActionSet associated with a column in the ADF Table component should invoke this action. The DoubleClickActionSet that invokes RowUpSync also changes the position of the ADF Table component's iterator on the Fusion web application to the current worksheet row (assuming it exists in the Fusion web application).

UnflagAllRows

Removes flags from cells in the _ADF_FlagColumn column.

For more information about the _ADF_FlagColumn, see Section 7.11.2, "Row Flagging in an ADF Table Component" and Section 7.12, "Special Columns in the ADF Table Component."

Upload

Uploads pending changes to the Fusion web application. Commits successful rows even if row failures occur.

For more information, see Section 7.8, "Configuring an ADF Component to Upload Changes from an ADF Table Component."

For more information about resolving data conflict between the Excel workbook and the Fusion web application, see Section 12.7, "Handling Data Conflicts When Uploading Data from a Workbook".

UploadAllOrNothing

Uploads pending changes to the Fusion web application. Commits successful rows only if none of the rows fail.

For more information about Upload action, see Section 7.8, "Configuring an ADF Component to Upload Changes from an ADF Table Component." For more information about UploadAllOrNothing action, see Section 7.9, "Configuring an ADF Table Component to Upload Changes Using UploadAllOrNothing Action."


A.10 ADF Read-only Table Component Properties and Actions

The ADF Read-only Table component exposes one action, Download. This action downloads the current rows in the table identified by the ADF Read-only Table property, TreeID. Table A-12 describes TreeID and the other properties that the ADF Read-only Table component supports.

Table A-12 ADF Read-only Table Component Properties

Name Type EL Description

Annotation

   

For information about this property, see Table A-1.

Columns

Array

N

References an array of read-only columns. For information about the properties that a column in this array can support, see Table A-13.

ComponentID

   

For information about this property, see Table A-1.

Position

   

For information about this property, see Table A-1.

RowLimit

   

For information about this group of properties, see Table A-9.

TreeID

Tree binding

N

References a tree binding ID from the page definition file associated with the current worksheet if the ADF Read-only Table component was created by inserting a tree binding into the worksheet.


Table A-13 lists alphabetically the properties that a column in the ReadOnlyColumn array can use.

Table A-13 ADF Read-only Table Component Column Properties

Name Type EL Description

Annotation

   

For information about this property, see Table A-1.

CellStyleName

String

Y

Write an EL expression that resolves to an Excel style name that is applied to each cell in the column.

HeaderLabel

String

Y

Write an EL expression that resolves to a label for the column header.

HeaderStyleName

String

Y

Write an EL expression that resolves to an Excel style name that is applied to each cell in the column header.

ID

String

N

Assign a name to the column to identify it and its purpose. The value that you assign for this property has no functional impact. However, you must specify a value and the value that you specify must be unique within the list of columns. It serves to help you keep track of columns in the ADF Read-only Table component.

OutputText

ADF Component

 

For information about the properties that this component supports, see Section A.3, "ADF Output Text Component Properties."


A.11 Action Set Properties

Table A-14 lists alphabetically the properties that you can configure for an action set.

Table A-14 Action Set Properties

Name Type EL Description

ActionOptions

   

This group of properties specifies options for invoking local and remote actions.

ActionOptions.AbortOnFailure

Boolean

N

When set to TRUE, the remaining actions in the array are not invoked if an action fails. If FALSE, all actions are invoked regardless of the success or failure of previous actions. The default value is TRUE.

ActionOptions.FailureActionID

Action binding

N

Specify the action binding to invoke if an action set does not complete successfully. For example, you could specify an action binding that rolls back changes made during the unsuccessful invocation of the action set.

ActionOptions.SuccessActionID

Action binding

N

Specify an action binding to invoke if an action set completes successfully. For example, you could specify an action binding that executes a commit action.

A value for this property is optional.

Actions

Array

N

Specifies an ordered array of actions. An action can be one of the following:

Alert

   

This group of properties determines if and how an alert-style dialog appears to the user to indicate that the requested action is complete. The dialog that appears contains one button that allows the user to acknowledge the message and dismiss the dialog. For information about how to display an alert message, see Section 8.2.8, "How to Provide an Alert After the Invocation of an Action Set."

Many properties in this group make use of EL expressions to retrieve string values from resource bundles. For more information about using EL expressions, see Section 10.2, "Using Resource Bundles in an Integrated Excel Workbook."

Alert.Enabled

Boolean

N

Set to TRUE to display an alert message to end users that notifies them when an action set operation completes successfully or includes one or more failures.

For more information, see Section 8.2.8, "How to Provide an Alert After the Invocation of an Action Set."

Alert.FailureMessage

String

Y

Specify an EL expression that evaluates to a message to appear in the dialog if errors occur during execution of the action set.

Alert.OKButtonLabel

String

Y

Specify an EL expression that evaluates to a message to appear in the OK button of the dialog.

Alert.SuccessMessage

String

Y

Specify an EL expression that evaluates to a message to appear in the dialog if no errors occur during the execution of the action set.

Alert.Title

String

Y

Specify an EL expression that evaluates to a message to appear in the title area of the dialog.

Annotation

   

For information about Annotation, see Table A-1.

Status

   

This group of properties determines if and how a status message appears during the execution of an action set. For information about how to display a status message, see Section 8.2.5, "How to Display a Status Message While an Action Set Executes."

Many properties in this group make use of EL expressions that reference string keys defined in resource bundles. For more information, see Section 10.2, "Using Resource Bundles in an Integrated Excel Workbook."

Status.Enabled

Boolean

N

If TRUE (default), a status window appears during the execution of the action set. If FALSE, no status window appears.

Status.Message

String

Y

Specify an EL expression to evaluate and display in the status window while the action set executes.

Status.Title

String

Y

Specify an EL expression to evaluate and display in the title area of the status window while the action set executes.

Status.Mode

String

N

Choose the visual appearance of progress bars. The valid values are Automatic, BothBarsAlways, MainBarOnly, DetailBarOnly, and MainMessageOnly.

Status.DetailStatusMessage

String

Y

Specify an optional EL expression or literal value that evaluates to a status message to appear as the associated action progresses.


A.11.1 Confirmation Action Properties

Table A-15 lists alphabetically the properties that the Confirmation action in the array of Actions of an action set supports. For information about the other properties the array of Actions and action sets use, see Table A-14.

Table A-15 Confirmation Action Properties

Name Type EL Description

Annotation

   

For information about Annotation, see Table A-1.

CancelButtonLabel

String

Y

An EL expression that is evaluated and displayed in the Cancel button at runtime.

OKButtonLabel

String

Y

An EL expression that is evaluated and displayed in the OK button at runtime.

Prompt

String

Y

An EL expression that is evaluated and displayed in the main area of the confirmation dialog at runtime.

Title

String

Y

An EL expression that is evaluated and displayed in the title area of the confirmation dialog at runtime.


A.11.2 Dialog Action Properties

Table A-16 describes the properties that the Dialog action in the array of Actions of an action set supports. For information about the other properties the array of Actions and action sets use, see Table A-14.

For information about how to use the properties in Table A-16 to invoke a web page from a Fusion web application, see Section 8.4, "Displaying Web Pages from a Fusion Web Application."

Table A-16 Dialog Action Properties

Name Type EL Description

Annotation

String

N

For information about this property, see Table A-1.

Page

String

N

Specify the web page that the action invokes. Relative and absolute URLs are valid values.

ShareFrame

Boolean

N

Set to TRUE (default) to execute the web page specified by the Dialog.Page property in the same data control frame as the Excel worksheet. If you specify an absolute URL, ADF Desktop Integration ignores the value of the Dialog.ShareFrame property.

Target

List

N

Specifies how the web page the action invokes is rendered. Select:

  • Popup to render the web page in a modal dialog within an embedded web browser.

  • TaskPane to render the web page in runtime task pane.

Title

String

Y

Write an EL expression that resolves to the title of the Dialog at runtime or write a literal string.

WindowSize

Integer

N

Specify the initial size in pixels of the dialog that appears to the user. Valid values range from 0 to 2147483647. Values will be revised upwards or downwards as appropriate at runtime if the specified values are too large or too small. The default value for Height is 625 and 600 for Width.


A.12 Workbook Actions and Properties

Table A-17 describes the actions that a workbook can invoke. For information about configuring ribbon buttons to invoke these actions, see Section 8.3.1, "How to Define a Workbook Command Button for the Runtime Ribbon Tab."

Table A-17 Workbook Actions

Action Description

Login

When invoked, this action creates a new session between the integrated Excel workbook and the Fusion web application.

If invoked when a session has already been established, it first invokes the Logout action internally to free that session. For a workbook running against a web application that is enforcing authentication, the Login action prompts the end user to provide valid user credentials.

Logout

When invoked, ADF Desktop Integration sends a request to the Fusion web application to invalidate the session between the integrated Excel workbook and the Fusion web application. After invoking this action, the end user must be authenticated the next time the Excel workbook accesses the Fusion web application.

ClearAllData

When invoked, this action clears all data entered by the user from cells that reference Oracle ADF bindings. Tables, such as those created by the ADF Table and ADF Read-only Table components, will be truncated so that they only display header rows with labels cleared. Values in cells that reference the Input Text or Output Text components are cleared. Column headers and labels are cleared as well. References to all resource bundles that the integrated Excel workbook uses are cleared. Worksheets that do not contain bindings or reference a page definition file remain unchanged. A dialog prompts the end user to confirm invocation of this action. Once the end user confirms invocation, ADF Desktop Integration executes the following events after invocation of the action:

  • Invokes the integrated Excel workbook's Logout action

  • Terminates the runtime session and clears all data from the integrated Excel workbook and all caches

  • Reinitializes the integrated Excel workbook and invokes the workbook's Login action

Invocation of the ClearAllData action does not change data hosted by the Fusion web application. One or more of the following actions must be invoked to change data hosted by the Fusion web application:

  • A worksheet's UpSync action

    This action synchronizes all data referenced by non-table type components. For more information, see Section A.13, "Worksheet Actions and Properties."

  • An ADF Table component's RowUpSync action can be used to synchronize any pending changes in a row to the Fusion web application. The ADF Table component's DeleteFlaggedRows action can be invoked to delete flagged rows. For more information about ADF Table component actions, see Section A.9.3, "ADF Table Component Actions."

EditOptions

When invoked, this action launches a dialog that shows the current value of the WebAppRoot property and allows the end user to enter a new value.

If the end user chooses to change the value of WebAppRoot, a confirmation dialog appears after the end user clicks OK. Once the change is confirmed, the following events occur:

  • Workbook ClearAllData action is invoked

  • Workbook Logout action is invoked

  • All data referenced by bindings in the workbook is removed

  • References to WebAppRoot are updated in the Excel workbook's configuration

  • Workbook Login action is invoked to authenticate the user with the Fusion web application that is specified as the value for WebAppRoot

    The ClearAllData workbook action clears all resource bundles referenced by the integrated Excel workbook. After WebAppRoot is changed, the integrated Excel workbook attempts to retrieve resource bundles from the Fusion web application as part of the reinitialization process. This request to the Fusion web application triggers the authentication process.

ViewAboutDialog

When invoked, this action launches a dialog called About that displays information defined in the BrandingItems workbook property and other information such as the versions of supporting software.


Table A-18 lists alphabetically the ADF Desktop Integration properties that an Excel workbook can use.

Table A-18 Workbook Properties

Name Type EL Description

ApplicationHomeFolder

String

N

Specify the absolute path to the directory that is the root for the JDeveloper application workspace (.jws) where you developed the desktop integration project.

For example, the value of this property in a workbook integrated with the Summit sample application for ADF Desktop Integration could be something similar to the following:

D:\Oracle\Applications\Summit_ADFdi

­ADF Desktop Integration prompts you to specify a value for this property the first time that you open an integrated Excel workbook.

For more information, see Section 4.2.2, "How to Configure a New Integrated Excel Workbook."

BrandingItems

Array

N

An array of name-value pairs that resolve to resource bundle references (for example, #{res['myAppName']}) or a literal string. Each pair in the array consists of a name and a value. Each name and value can reference a literal string or an EL expression.

For information about branding your integrated Excel workbook, see Section 9.6, "Branding Your Integrated Excel Workbook."

Login.WindowSize

Integer

N

Specify the initial size in pixels of the login dialog that appears to the user. Valid values range from 0 to screen width or height. Values will be revised upwards or downwards as appropriate at runtime if the specified values are too large or too small. The default value for Height is 625 and Width is 600.

Parameters

Array

N

An array of workbook initialization parameters that you configure to pass the parameters from a page in a Fusion web application to an integrated Excel workbook. You can define multiple workbook initialization parameters in the Fusion web application's page. Each workbook initialization parameter (parameter that references a URL argument) that you define in a page must be specified in a Parameter property of this array, otherwise it is ignored.

Each element in the array supports the following properties:

  • Annotation

    For more information about this property, see Table A-1.

  • Parameter

    You specify the name of the workbook initialization parameter you defined in the page of the Fusion web application from which the end user downloads the integrated Excel workbook.

For information about using this property, see Section 14.5, "Passing Parameter Values from a Fusion Web Application Page to a Workbook."

Project

String

N

Specify the name of a JDeveloper project in the current JDeveloper workspace. ADF Desktop Integration attempts to load the .jpr file that corresponds to the project that you specify. An error appears if the .jpr file is not available or is not in the expected format.

When you open an integrated Excel workbook for the first time in design mode, ADF Desktop Integration searches for a .jpr file in the parent folder hierarchy. If it finds a .jpr file, it sets the value of Project to the name of the project that corresponds to the .jpr file.

ADF Desktop Integration loads the names of the available projects from the application_name.jws file specified by ApplicationHomeFolder.

RemoteServletPath

String

N

Specify the path to the ADF Desktop Integration remote servlet. This path must be relative to the value specified for WebAppRoot. Note that the value you specify for RemoteServletPath must match the value that is specified in the web application's deployment descriptor file (web.xml). The default value for this property is:

/adfdiRemoteServlet

Resources

Array

N

Specifies an array of resource bundles to register with the workbook. Each element in the array supports the following properties:

  • Alias

    Specify a string value that is unique within Workbook.Resources. EL expressions use this string to reference the resource bundle.

  • Annotation

    For more information about this property, see Table A-1.

  • Class

    Specify a fully qualified class name, but do not include the file extension. The class name that you specify is expected to be a Java resource bundle class that the Fusion web application you integrate your workbook with uses.

    For example, the EditCustomers-DT.xlsx workbook in the Summit sample application for ADF Desktop Integration references the following resource bundle:

    oracle.summitdi.resources.UIStrings
    

For more information, see Section 10.2, "Using Resource Bundles in an Integrated Excel Workbook."

Runtime Ribbon Tab

-

-

This group of properties defines whether and how a Ribbon tab appears in Excel at runtime. The following entries in this table describe the properties in the Runtime Ribbon Tab group. For more information about Ribbon tab and its commands, see Section 8.3, "Configuring the Runtime Ribbon Tab."

Runtime Ribbon Tab.Annotation

String

N

For information about this property, see Section A.1, "Frequently Used Properties in the ADF Desktop Integration."

Runtime Ribbon Tab.Visible

Boolean

N

If TRUE,the Ribbon tab appears at runtime. The Ribbon tab does not appear if you set Enabled to FALSE. TRUE is the default value.

Runtime Ribbon Tab.Title

String

Y

Specify an EL expression that evaluates to the title that appears for the Ribbon tab in the title area. Excel imposes a maximum limit of 1024 characters for Ribbon tab titles. Ensure that the runtime value of the EL expression you specify does not exceed 1024 characters as ADF Desktop Integration truncates the value so that Excel does not generate an error message.

If you choose to assign a key tip character using the & character, consider avoiding the letter K for the Runtime Ribbon Tab.Title. Excel does not allow the letter K to be used here when the workbook is running in the ar_SA culture.

Runtime Ribbon Tab.Workbook Commands

Array

N

Each element in this array corresponds to a workbook command at runtime. Each element in the array uses the following properties:

  • Annotation

    For more information about this property, see Table A-1.

  • Label

    For more information about this property, see Table A-1.

    If you want the & character to appear in the command label, you must specify &&. Excel interprets a single & character as a special character, and assigns the next character after & as the keyboard accelerator for the workbook command at runtime.

  • Method

    Specify the workbook action that the workbook ribbon button invokes. For more information about workbook actions, see Table A-17.

WebAppRoot

String

N

A fully qualified URL to the Fusion web application's root.

WebPagesFolder

String

N

Specify the path to the directory that contains the web pages that you intend to use with your integrated Excel workbooks. The value that you specify for the path most be relative to the value of ApplicationHomeFolder.

WorkbookID

String

N

A unique identifier for the integrated Excel workbook. ADF Desktop Integration generates the unique identifier when you open the workbook for the first time in design mode.

The value cannot be modified. However, ADF Desktop Integration can generate a new value if you use the Reset WorkbookID link in the Edit Workbook Properties dialog.

The value of this property is used during tamper check, as described in Section 11.3, "Checking the Integrity of an Integrated Excel Workbook's Metadata."


A.13 Worksheet Actions and Properties

An Excel worksheet with ADF Desktop Integration can invoke the following actions:

  • UpSync

    Synchronizes any pending changes from the ADF Input Text and ADF List of Values components in the worksheet to the Fusion web application.

  • DownSync

    Downloads any changes from the Fusion web application to the ADF Input Text, ADF Output Text, and ADF List of Values components in the worksheet.

  • DisplayWorksheetErrors

    Displays a detailed list of errors in a message dialog for the integrated Excel worksheet if any errors are available. Invoke this action in an action set that is invoked by an ADF component (other than the ADF Table-type components) or a worksheet ribbon button.

When you configure an ADF Button component to invoke an action binding or method action binding, the action set to invoke when a user clicks the ADF Button component at runtime is populated as follows by default:

  1. UpSync

  2. Action or method action binding that you specify for the ADF Button component

  3. DownSync

If the first action that you invoke on a worksheet with an empty form is the UpSync worksheet action, you may encounter errors. For this reason, ensure that the first action invoked is the DownSync worksheet action. You can configure the ADF Button component's action set or one of the worksheet events (Startup or Activate) described in Table A-19 to invoke the DownSync worksheet action first.

Table A-19 describes the ADF Desktop Integration properties that an Excel worksheet can use.

Table A-19 Worksheet Properties

Name Type EL Description

Annotation

String

N

For information about this property, see Table A-1.

Events

Array

N

Each element in this array specifies an action set to invoke if the associated worksheet event occurs. For information about action sets, see Section A.11, "Action Set Properties." For information about worksheet events, see the entry in this table for Events.n.Event.

The following entries in this table prefaced by Events.n describe the properties that an element in this array supports where n refers to a specific element in the array.

Events.n.ActionSet

ActionSet

N

For more information about the properties of action sets, see Section A.11, "Action Set Properties."

Events.n.InvokeOnceOnly

Boolean

N

The default value of this property is FALSE.

When set to TRUE, the workbook stores information about whether the worksheet invoked the action set for this event and, if so, prevents the worksheet from invoking the action set a second time. Note that if the workbook is not saved, this information is lost. This means that the worksheet can invoke the event again the next time that the workbook opens.

Events.n.Annotation

String

N

For information about the annotation property, see Table A-1.

Events.n.Event

List

N

The worksheet supports the following events that you can configure to invoke an action set:

  • Startup

    Excel workbook opens and the worksheet is activated for the first time.

  • Shutdown

    Excel workbook closes or Excel application exits.

  • Activate

    User navigates to the current worksheet.

  • Deactivate

    User navigates away from the current worksheet or Shutdown event triggered.

Note that the worksheet events complete execution even if the action sets that they invoke fail.

For more information about worksheet events and action sets, see Section 8.2.4, "How to Invoke an Action Set from a Worksheet Event."

Protection.Mode

List

N

The worksheet provides two options:

  • Off

    Worksheet protection is not used at runtime.

  • Automatic

    Worksheet protection is enabled automatically at runtime.

The default value for this property is Off.

Protection.Password

String

N

Specify a password to prevent end-users from turning off sheet protection at runtime. The maximum password length allowed by Excel is 255 characters.

Ribbon Commands

Array

N

Specify one or more workbook actions that appear as commands at runtime. Each command is an element in the WorksheetMenuItem array. Entries in this array support the following properties:

  • Annotation

  • Label

  • SelectActionSet

For more information about the Annotation and Label properties, see Table A-1. For more information about the SelectActionSet property, see Section A.11, "Action Set Properties."

If you want the & character to appear in the command label, you must specify &&. Excel interprets a single & character as a special character, and assigns the next character after & as the keyboard accelerator for the worksheet command at runtime.

Page Definition

String

N

Specify the page definition file to associate with the worksheet. For information about page definition files, see Section 4.3, "Working with Page Definition Files for an Integrated Excel Workbook."

Parameters

Array

N

An array of worksheet parameters that you configure to pass the parameters from a workbook Parameters property to a worksheet in an integrated Excel workbook. Each element in the array supports the following properties:

  • Annotation

    For more information about this property, see Table A-1.

  • Parameter

    Specify the ID of a parameter element that you added to the page definition file associated with the worksheet.

  • Value

    Write an EL expression that references the value of the Parameter property you specified for the workbook initialization parameter (workbook Parameters.Parameter property). The workbook Parameters.Parameter property supplies this value the first time that the page definition file associated with this worksheet is initialized.

For information about using this property, see Section 14.5, "Passing Parameter Values from a Fusion Web Application Page to a Workbook."

RowData

   

Set values for the CachedAttributes property when you want to cache data in an integrated Excel workbook across a multiple sessions with the Fusion web application.

Set a value for the ChangeIndicatorAttributeID property to determine if a row has been modified by another user since you downloaded it from the Fusion web application.

RowData.CachedAttributes

Array

N

Specify values for the properties in this array to determine the attributes for which data is cached. Each CachedAttribute element in this array supports the following properties:

  • AttributeID

    This property references the attribute binding for which data is to be cached. Do not specify an attribute binding for AttributeID and as an editable field in a form (for example, in an ADF Input Text component) in the same worksheet.

  • Annotation

    For more information about this property, see Table A-1.

For more information about clearing the values of cached attributes, see Section 7.19, "Clearing the Values of Cached Attributes in an ADF Table Component."

RowData.ChangeIndicatorAttributeID

Binding

N

Specify the row-specific attribute of the tree binding used to determine if a row has been modified by another user since the row was last downloaded by to your integrated Excel workbook.

For more information, see Section 12.7, "Handling Data Conflicts When Uploading Data from a Workbook."

ServerContext

   

This group of properties references the attribute bindings that uniquely identify the row displayed in the current worksheet so that you can reestablish server data context across multiple sessions.

For more information, see Section 15.2, "Restore Server Data Context Between Sessions."

ServerContext.CacheDataContexts

Array

N

Add elements to the CacheDataContexts array for cases where there is more than one iterator defined in the binding container whose server-side context must be reestablished. The CacheDataContexts array supports the following properties to store the worksheet's cached data context:

  • RestoreDataContextActionID

    References an action binding to invoke.

  • CachedServerContexts

    An array that identifies the attribute binding values to cache and set before the action binding specified by RestoreDataContextActionID is invoked. Each element in the CachedServerContext array supports the CachedAttributeID and RestoredAttributeID properties. CachedAttributeID identifies the attribute binding value to cache in the worksheet. RestoredAttributeID is an optional property for which you specify a value when the destination attribute binding value is different from the source attribute binding value. If you do not specify a value for RestoredAttributeID, the value of CachedAttributeID is used as the destination attribute binding value and its value is set before invoking the action set.

  • Annotation

    For more information about this property, see Section A.1, "Frequently Used Properties in the ADF Desktop Integration."

ServerContext.IDAttributeID

Binding

N

Specifies an attribute binding that uniquely identifies the row displayed in the current worksheet. This property is used at runtime to determine whether the server context has been reestablished properly for non-table type components in the worksheet.

ServerContext.SendParameters

Boolean

N

The default value of this property is FALSE.

When set to TRUE, the workbook sends initialization parameters for this worksheet when reestablishing context across multiple sessions.

SetupActionID

Binding

N

Specify the ADFm action binding to be invoked before the binding container metadata is retrieved.

A value for this property is optional.

If two, or more, worksheets are using the same page definition, the action binding specified for the last worksheet will be invoked. Hence, create a page definition for each worksheet and do not specify a page definition to multiple worksheets.

Title

String

Y

Specifies an EL expression that resolves to a string and sets the name of the worksheet. At design time, the EL expression can be of any length and can include the following special characters:

[ ] \ / * ?

At runtime, the evaluated string can display a maximum of 31 characters and ignores the above special characters. If the length of the evaluated string exceeds 31 characters, the extra characters are truncated and are not displayed.

Note that the Title property does not support binding parts in the EL expression. The expected usage is a resource-type expression.

Ensure that the EL expressions you write for the Title property generate unique values for each worksheet at runtime and contain fewer than 31 characters.


Close Window

Table of Contents

Developing Applications with Oracle ADF Desktop Integration

Expand | Collapse