This chapter includes the following sections:
The ADF Desktop Integration Form-type components allow end users to manage data retrieved from the Fusion web application in the integrated Excel workbook.
ADF Desktop Integration uses the following components to create form-type functionality in an integrated Excel workbook:
ADF Input Text
ADF Input Date
ADF Output Text
ADF Label
ADF List of Values
ADF Image
Figure 6-1 shows some of these components. Note that the ribbon commands shown in Figure 6-1 are worksheet-level ribbon commands that appear in the Excel Ribbon of your integrated Excel workbook at runtime. See Configuring the Runtime Ribbon Tab.
Use of the ADF List of Values component is described in Creating a List of Values in an Excel Worksheet.
Figure 6-1 ADF Desktop Integration Form-Type Components
The ADF Desktop Integration form-type components are used to build forms in the integrated Excel workbook for user input, and output from the Fusion web application. As shown in Figure 6-2, the form-type components used in the navigation form of EditWarehouseInventory-DT.xlsx
enable end users to navigate and update data.
Figure 6-2 Using ADF Desktop Integration Form-Type Components
After you have added a component to the worksheet, you may find that you need to add functionality such as responding to events or end user actions. Following are links to other functionality that form components can use:
Lists of values: You can use an ADF List of Values component to create a list of values in your integrated Excel workbook. See Working with Lists of Values .
ADF Label or ADF Output Text components to display output from a managed bean. See Displaying Output from a Managed Bean in an ADF Component.
Displaying output from a managed bean: You can use ADF Label or ADF Output Text components to display output from a managed bean. See Displaying Output from a Managed Bean in an ADF Component.
Styles: You can configure the display of your form-type components using several predefined Excel styles. See Working with Styles.
EL Expressions: You can use EL expressions with form-type components. See ADF Desktop Integration EL Expressions.
The ADF Label component is a component that you can insert into the active worksheet to display a static string value.
You specify a value in the input field for Label
in the property inspector or alternatively you invoke the expression builder to write an EL expression that resolves to a string at runtime. The retrieved string can be defined in a resource bundle or in an attribute control hint for an entity or view object. For example, the following EL expression resolves to the value of label of CountryId attribute binding at runtime:
#{bindings.CountryId.label}
The value that you specify for the Label
property in an ADF Label component or other Oracle ADF components is evaluated after the worksheet that hosts the Oracle ADF component is initialized (opened for the first time).
You can configure a number of properties for the component, such as style and position, in the worksheet using the property inspector.
Figure 6-3 shows an ADF Label component with its property inspector in the foreground. The ADF Label component references an EL expression that resolves to the label of CountryId attribute binding at runtime.
Figure 6-3 ADF Label Component in Design Mode
To insert an ADF Label component:
Figure 6-4 shows an example of the ADF Label component (in black box) at runtime.
Figure 6-4 ADF Label Component at Runtime
Note:
An ADF Label component renders only once, and is not updated after a call to Worksheet.DownSync
. Consider using an ADF OutputText component instead if you want the displayed value to change after a call to Worksheet.DownSync
.
For information about using labels in an integrated Excel workbook, see Using Labels in an Integrated Excel Workbook.
The ADF Input Text component is a component that you insert into the active worksheet using the components palette.
At runtime, the active cell in the worksheet where you inserted the component displays the current value from the component's binding after the worksheet DownSync
action is invoked. End users can edit this value at runtime. Configure the worksheet UpSync
action to transfer changes end users make to the value to the Fusion web application. Configure a Commit
action binding to commit the changes in the Fusion web application.
You can configure a number of properties for the component, such as its position, style and behavior when a user double-clicks the cell (DoubleClickActionSet
properties), in the worksheet using the property inspector. For information about DoubleClickActionSet
, see Using Action Sets.
Figure 6-5 shows an ADF Input Text component with its property inspector in the foreground. The ADF Input Text component binds to the City
attribute binding in the Summit sample application for ADF Desktop Integration. The end user enters a city name in this component.
For information about the ADF Input Text component's properties, see ADF Input Text Component Properties.
Figure 6-5 ADF Input Text Component in Design Mode
To insert an ADF Input Text component:
Figure 6-6 shows an example of the ADF Input Text component (in black box) at runtime.
Figure 6-6 ADF Input Text Component at Runtime
The ADF Output Text component is a component that you can insert into the active worksheet using the components palette. The active cell in the worksheet when you insert the component displays the current value from the component's binding after you invoke the worksheet DownSync
action.
The value the component displays is read-only. Changes that the end user makes to the value in the cell that anchors the component are ignored when changes are sent to the Fusion web application. To prevent end users from altering the cell contents, enable automatic sheet protection in worksheet properties, as described in Using Worksheet Protection.
This component can also serve as a subcomponent for the ADF Table and ADF Read-only Table components. Columns in the ADF Table and ADF Read-only Table components can be configured to use the ADF Output Text component.
You can configure a number of properties for the component such as style, behavior when a user double-clicks the cell (DoubleClickActionSet
properties), and position, in the worksheet using the property inspector.
Figure 6-7 shows an ADF Output Text component with its property inspector in the foreground.
Figure 6-7 ADF Output Text Component in Design Mode
To insert an ADF Output Text component:
Figure 6-8 shows an example of the ADF Output Text component (in black box) at runtime.
Figure 6-8 ADF Output Text Component at Runtime
The ADF Input Date component displays a date picker at runtime that enables the end user to choose a date value for a date-type field.
At design-time, you can specify an attribute binding or an EL expression that resolves to a date-time value at runtime in the input field for Value. Other date-time values are not supported.
Figure 6-9 shows an ADF Input Date component at design-time.
Figure 6-9 ADF Input Date Component in Design Mode
You can insert the ADF Input Date component as a field in a form, or as a column in a table component. You can also add the ADF Input Date component as a model-driven column with date attribute.
To insert an ADF Input Date component:
Figure 6-10 shows an example of the ADF Input Date component at runtime.
Figure 6-10 ADF Input Date Component at Runtime
At runtime, when selected, the ADF Input Date component displays a calendar in a modeless window. The end user can pick a date from the displayed month, or use the arrow icons to navigate to other months. You can also click the month or the year to navigate to another month, year, or decade (see Figure 6-11).
End users can enter a time manually in the cell that hosts the ADF Input Date component. To accept this input from your end users, configure the Excel's Format Cells properties to permit entry of a time value along with a date value in the cell that hosts the ADF Input Date component. The ADF binding type determines whether the time value will be used. By default, the time value defaults to 0:00
.
Figure 6-11 Navigation in ADF Input Date Component at Runtime
Using the ADF Image component, you can insert an image in the integrated Excel worksheet. At design time, specify the URL of the image file in Source
, and the ADF Image component renders the image at runtime. The image is rendered at original size at runtime.
At runtime, when the ADF Image component renders, ADF Desktop Integration determines whether the Source
property value is an absolute URL or a relative URL. The source URL is considered to be absolute if it starts with http
and https
, the only supported schemes. If the URL is absolute, it is used as is to fetch the image and insert that image into the worksheet. If the URL is not absolute, the partial URI is assumed to be relative to the workbook's WebAppRoot
. In such a case, the WebAppRoot
value and the Source
value are concatenated to form the complete image URL.
If the image does not render at runtime for any reason (for example, an invalid URL), the short description text that you configure at design time appears instead of the image and ADF Desktop Integration creates a log entry. The technical details regarding the failure are reported in the client logs. ADF Desktop Integrate does not interrupt the worksheet initialization and does not present a warning or error message to the end user. The end user sees the short description of the image in the cell location where the image would have displayed in the case of success.
Figure 6-12 shows an ADF Image component at design time.
Figure 6-12 ADF Image Component in Design Mode
To insert an ADF Image component:
Figure 6-13 shows an example of the ADF Image component at runtime.
Figure 6-13 ADF Image Component at Runtime
Note:
If the worksheet is not protected, the end user may resize or move the image at runtime. Depending on the size of the image, it might appear over (and hide) other worksheet contents, including other ADF Desktop Integration components.
You can configure an ADF component to display output from a managed bean in your Fusion web application.
You reference a managed bean in an integrated Excel workbook through an EL expression. Add a method action binding to the page definition file you associate with the Excel worksheet to retrieve the value of the managed bean and assign it to an attribute binding. Use an EL expression to retrieve the value of the attribute binding at runtime.
Information about how to use managed beans in a Fusion web application can be found in Using a Managed Bean in a Fusion Web Application ofDeveloping Fusion Web Applications with Oracle Application Development Framework.
You write an EL expression for a property that supports EL expressions (for example, the Label
property).
Before you begin:
It may be helpful to have an understanding of managed beans. See Displaying Output from a Managed Bean in an ADF Component.
You may also find it helpful to understand the functionality that can be added using other ADF Desktop Integration features. See Additional Functionality for ADF Desktop Integration Form-Type Components.
To display output from a managed bean:
The method action binding retrieves values from the managed bean and populates the attribute binding. The EL expression that you write retrieves the value from the attribute binding and displays it to the end user through the ADF component that you configured to display output. For example, the ADF Label component shown in design mode in Figure 6-15 displays a string similar to the following at runtime:
Connected as sking
Figure 6-15 Output from a Managed Bean at Runtime
In Figure 6-15, sking
is the user name of the user that is logged on to the Fusion web application through the integrated Excel workbook.
The ADF Desktop Integration module supports EL expressions within components that allow a single component to display data that is based on a calculation or concatenation of multiple binding expressions.
You write an EL expression for the Value
property of an Input Text or Output Text component.
Figure 6-16 shows an EL expression example where an ADF Output Text component is configured to display the margin between two fields: List Price and Cost Price.
Figure 6-16 ADF Output Text Component Displaying Calculated Data
Before you begin:
It may be helpful to have an understanding of how to display concatenated or calculated data in ADF components. See Displaying Concatenated or Calculated Data in Components.
You may also find it helpful to understand the functionality that can be added using other ADF Desktop Integration features. See Additional Functionality for ADF Desktop Integration Form-Type Components.
To create an EL expression to display calculated data
For information about EL expressions, see ADF Desktop Integration EL Expressions.
Note:
If the Value
property of an ADF Input Text component contains a formula, the ADF Input Text component becomes read-only at runtime regardless of the value of the ReadOnly
property.
You can insert a form component or a binding in a merged cell, or merge cells after inserting the form component or binding, but you cannot insert multiple form components in a merged cell or merge cells that are occupied by different form components.
Before you insert a component in a merged cell, make a note of the following:
Drag-and-drop functionality is not supported for inserting component in a merged cell.
Do not merge a component cell with non-empty cells that are above or left to it. When two or more cells are merged, Excel keeps the data and style of the most upper-left cell and discards the data of the remaining cells. So, merging a component cell with a non-empty cell above or left to itself results in the component data being overwritten.
Do not merge an empty component cell that has no value or binding with empty cells above or left to it. Merging an empty component cell with empty cells above or left to itself results in the style of that component cell being overwritten.