6 Working with ADF Desktop Integration Form-Type Components
This chapter includes the following sections:
6.1 About ADF Desktop Integration Form-Type Components
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. For more information, 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
6.1.1 ADF Desktop Integration Form-Type Components Use Cases and Examples
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 navigation form of EditWarehouseInventory-DT.xlsx enable end users to navigate and update data.
Figure 6-2 Using ADF Desktop Integration Form-Type Components
6.1.2 Additional Functionality for 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. For more information, see Working with Lists of Values .
ADF Label or ADF Output Text components to display output from a managed bean. For more information, 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. For more information, 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. For more information, see Working with Styles.
-
EL Expressions: You can use EL expressions with form-type components. For more information, see ADF Desktop Integration EL Expressions.
6.2 Inserting an ADF Label Component
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:
- Open the integrated Excel workbook.
- Select the cell in the Excel worksheet where you want to anchor the component.
- In the components palette, select ADF Label and click Insert Component. Alternatively, in the Oracle ADF tab, select ADF Label from the Insert Component dropdown list
- Configure properties in the property inspector to determine the appearance, design, and layout of the component.
- Click OK.
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 more information about using labels in an integrated Excel workbook, see Using Labels in an Integrated Excel Workbook.
6.3 Inserting an ADF Input Text Component
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 more 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.
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
6.4 Inserting an ADF Output Text Component
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
6.5 Inserting an ADF Input Date Component
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
6.6 Inserting an ADF Image Component
Using the ADF Image component, you can insert an image (for example, a company logo) 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.
6.7 Inserting an ADF Button Component
ADF Button components are deprecated. Do not add new ADF Button components to your integrated Excel workbooks. Replace existing ADF Button components with worksheet-level ribbon commands. For more information, see How to Configure a Worksheet Ribbon Command for the Runtime Ribbon Tab.
The ADF Button component renders a button in the Excel worksheet at runtime. End users click this button to invoke one or more actions specified by the ClickActionSet group of properties.
For more information about the properties of the ADF Button component, see ADF Button Component Properties . The follow notes describe technical limitations with ADF Button components.
Note:
-
If you change the view mode of the Excel worksheet to the Page Layout or Page Break mode, the ADF Button components may be rendered in an unexpected position. You must return back to Normal mode without saving the workbook, and then Run and stop the integrated Excel workbook to render the buttons to their original positions.
-
You can modify the properties of the component at a later time by selecting the cell in the worksheet. Click the ADF Button component to open its property inspector.
-
The ADF Button components are active at 100% zoom only, and are disabled when the end user zooms in or out on an integrated Excel worksheet.
-
To remove the component, use the Delete ribbon command. For more information, see Removing ADF Desktop Integration Components.
Tip:
In design mode, you can click the button, or press the spacebar when the button is in focus, to open the property inspector. Buttons do not respond to a mouse right-click.
You need to perform the following procedure once if you plan to use ADF Button components in your integrated Excel workbook.
To allow Excel to run an integrated Excel workbook that uses ADF Button components:
- In the Trust Center dialog, choose the Macro Settings tab, and then click the Trust access to the VBA project object model checkbox, as shown in Figure 6-14.
Figure 6-14 Excel Trust Center Dialog
6.8 Displaying Output from a Managed Bean in an ADF Component
You can configure an ADF component to display output from a managed bean in your Fusion web application. Information about how to use managed beans in a Fusion web application can be found in the "Using a Managed Bean in a Fusion Web Application" section of Developing Fusion Web Applications with Oracle Application Development Framework. 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.
6.8.1 How to Display Output from a Managed Bean
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. For more information, 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. For more information, see Additional Functionality for ADF Desktop Integration Form-Type Components.
To display output from a managed bean:
- Select the ADF component to display the output from the managed bean, and open its property inspector.
Figure 6-15 shows an example where an ADF Label component is configured to display the output from an attribute binding that has its value populated by an action binding.
Figure 6-15 ADF Label Component That Displays Output from a Managed Bean at Runtime
6.8.2 What Happens at Runtime: How an ADF Component Displays 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-16 displays a string similar to the following at runtime:
Connected as sking
Figure 6-16 Output from a Managed Bean at Runtime
In Figure 6-16, sking is the user name of the user that is logged on to the Fusion web application through the integrated Excel workbook.
6.9 Displaying Concatenated or Calculated Data in Components
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.
6.9.1 How to Configure a Component to Display Calculated Data
You write an EL expression for the Value property of an Input Text or Output Text component.
Figure 6-17 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-17 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. For more information, 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. For more information, see Additional Functionality for ADF Desktop Integration Form-Type Components.
To create an EL expression to display calculated data
For more 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.
6.9.2 Using Form Components and Merged Cells
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.