You can customize the appearance of ADF Desktop Integration components using styles. For example, Figure 10-1 shows various styles applied to the columns of ADF Table in EditCustomers-DT.xlsx.

Figure 10-1 Styles Applied to Columns of ADF Table in EditCustomers-DT.xlsx

After you have applied styles to configure the appearance of your integrated Excel workbook, you may find that you need to add additional functionality to configure your workbook. The following sections describe other functionality that you can use:

• Branding: In addition to styles, ADF Desktop Integration provides a collection of properties (BrandingItems) that enable you to brand your integrated Excel workbook with application name, application version details, and copyright information. See Branding Your Integrated Excel Workbook.

• Localization: You can customize the integrated Excel workbook as part of the process to internationalize and localize with the Fusion web application. See Internationalizing Your Integrated Excel Workbook.

Many properties have default values that are drawn from a predefined list of ADF Desktop Integration styles. For example, the HeaderStyleName property's default value is Column Header, one of the predefined styles in ADF Desktop Integration. ADF Desktop Integration automatically adds these predefined styles to the Excel workbook when it is enabled for use with ADF Desktop Integration. The predefined styles that ADF Desktop Integration provides are consistent with the Oracle Alta UI, described in http://www.oracle.com/webfolder/ux/middleware/alta/index.html.

The following is the list of predefined styles:

• Styles for forms:

  • Form Header

  • Form SubHeader

  • Input Text

  • Label

  • Output Text

• Styles for tables:

  • Column Header

  • Data Cell

  • Indicator Cell

  • Key Cell

  • Read-only Cell

  • Status Cell

• Branding Area

You may create additional styles for use in your Excel workbook. For example, to add a date-specific formatting, you can duplicate Data Cell, call it My Date Cell, and add your date-specific formatting.

Once you have decided what styles to apply to the ADF Desktop Integration components at runtime, you can write EL expressions to associate a style with a component. The ADF Desktop Integration component properties that include StyleName in their name take an EL expression as a value. The ADF Label component and the Label property of other ADF components also support EL expressions. These EL expressions can retrieve the values of string keys defined in resource bundles or the values of attribute control hints defined in your Fusion web application.

For information about creating new styles and merging styles into a workbook, see Excel's documentation.

Some formats in the Date category of the Number styles that Excel can apply to cells change if a user changes the locale of the local system using the Regional and Language Options dialog that is accessible from the Microsoft Windows Control Panel. The * character precedes these formats in the Type list. Figure 10-2 shows the Regional and Language Options dialog where an example of a Date type that formats dates in a cell using French (France) conventions appears.

Figure 10-2 French Date Formats in Excel

If the end user changes the regional options of a system to use English (United States), as illustrated in Figure 10-3, the cells that are formatted with the style in Figure 10-2 use the English (United States) conventions.

Figure 10-3 US English Date Formats in Excel

Description of "Figure 10-3 US English Date Formats in Excel"

1. In the integrated Excel workbook, select the cell that references the Oracle ADF component you want to modify and then click the Edit Properties button in the Oracle ADF tab.
2. Select the StyleName property and click the browse (...) icon to display the Edit Expression dialog.
3. Expand the Styles node and select the style to apply to cell at runtime.

   For example, apply an Output Text style to the Binding Warehouse ID output text field.

4. Click Insert Into Expression to insert the selected style into the Expression field.

   Figure 10-4 shows the Edit Expression dialog where we define the style for the OutputText component that displays the Warehouse ID in the Summit sample application's EditWarehouseInventory-DT.xlsx workbook.

   Figure 10-4 Edit Expression Dialog Applying a Style

   
5. Click OK.

The EL expression that you entered as a value for the property with StyleName in its name is evaluated at runtime. If it corresponds to one of the predefined styles or one that you defined, the style is applied to the ADF component that you set the property for.

If a style is applied to a cell that references an ADF component, the ADF component overwrites that style at runtime with any property values (font, alignment, and so on) defined by the style referenced by its StyleName property.

For example, Figure 10-5 shows the runtime appearance of the Warehouse ID field defined by the Output Text style in the Summit sample application's EditWarehouseInventory-DT.xlsx workbook.

Figure 10-5 Runtime Appearance of Component with Style Applied

When evaluating EL expressions at runtime, ADF Desktop Integration determines the value that the EL expression references. It then replaces the EL expression in the Excel formula with the value. In Example 10-1, ADF Desktop Integration first determines that value of the binding expression, #{bindings.Status}, in the following Excel formula:

=IF("#{bindings.Status}" = "Closed", "MyReadOnlyStyle", "MyReadWriteStyle")

It then replaces the binding expression with the runtime value, as in the following example, where the expression evaluated to Closed:

=IF("Closed" = "Closed", "MyReadOnlyStyle", "MyReadWriteStyle")

Excel evaluates the formula and, in this example, applies the MyReadOnlyStyle style.

You write EL expressions for the Oracle ADF component properties that support EL expressions in the Edit Expression dialog that is accessible from the Oracle ADF component's property inspector. Figure 10-6 displays an Edit Expression dialog launched from the property inspector window of a ribbon command.

Figure 10-6 Edit Expression Dialog

Before you begin:

It may be helpful to have an understanding of how to apply styles dynamically. See Applying Styles Dynamically Using EL Expressions.

You may also find it helpful to understand the functionality that can be added using other ADF Desktop Integration features. See Additional Functionality for Configuring the Appearance of an Integrated Excel Workbook.

To write an EL expression that applies a style at runtime:

1. Open the integrated Excel workbook.
2. Select a cell in the Excel worksheet that references the Oracle ADF component for which you want to write an EL expression.
3. Click the Edit Properties button in the Oracle ADF tab to display the property inspector.
4. Select the property in the property inspector with which you want to associate an EL expression and click the browse (...) icon to display the Edit Expression dialog.

   Note:

   The Edit Expression dialog appears only if the Oracle ADF component that you selected in Step 2 supports EL expressions. Depending on the context, the browse (...) icon can launch other editors such as the Edit Action dialog.

   The Edit Expression dialog, as illustrated in Figure 10-6, displays a hierarchical list of the Oracle ADF components, bindings, styles, resources, and Excel functions that you can reference in EL expressions. For information about the syntax of EL expressions that you enter in this dialog, see ADF Desktop Integration EL Expressions.

Note the following points about EL expressions that apply styles:

• EL expressions that evaluate to styles are applied when:

  • An ADF Table component invokes its Download or DownloadForInsert actions

  • Rows are inserted into an ADF Table component

  • An action set invokes a worksheet DownSync action

• EL expressions that evaluate to styles are not applied when:

  • A row-level action set invokes an ADF Table component RowDownSync action

  • The end user edits the format properties of a cell

  • An EL expression that evaluates to a style is not reevaluated when an end user edits a cell's value.

  • The runtime value of an EL expression does not match a style defined in the end user's integrated Excel workbook

    In this scenario the style formats of the targeted cells do not change. Instead, they retain their existing style formats. If you configured client-side logging, ADF Desktop Integration generates an entry in the log file when an EL expression evaluates to a style that is not defined in the end user's integrated Excel workbook. For information about client-side logging, see Generating Log Files for an Integrated Excel Workbook.

  • When a user navigates between cells or during upload. ADF Desktop Integration does not evaluate or apply styles during these end user actions.

• In Excel, given a workbook with various custom named styles, if you save a copy of that workbook from Excel, Excel automatically (and silently) deletes any custom named style that is not applied to any cell.

  If you have styles that are only used in EL expressions and not applied to any cell, Excel may delete them.

• The ADF Desktop Integration Publish feature creates a copy of the workbook. Hence, unused styles can disappear. The workaround is to apply each style once to an unused cell on an unused worksheet.

Figure 10-7 shows a portion of the design time view of the EditWarehouseInventory-DT.xlsx workbook in the Summit sample application for ADF Desktop Integration. It shows an ADF Label component that uses an EL expressions to retrieve the value of its Label property.

Figure 10-7 Design Time View of an ADF Label Component and an ADF Input Text Component with Label Property

At runtime, this EL expression resolves to a string key defined in the res resource bundle that is registered with the Summit sample application for ADF Desktop Integration. You define resource bundles in the workbook properties dialog. For information about referencing string keys from a resource bundle, see Using Resource Bundles in an Integrated Excel Workbook.

Figure 10-8 shows the corresponding runtime view of the ADF Label component illustrated in design mode in Figure 10-7.

Figure 10-8 Runtime View of an ADF Label Component

In addition to string keys from resource bundles, the ADF Label component and the Label property of other ADF components can reference attribute control hints that you define for entity objects and view objects in your JDeveloper project. Figure 10-9 shows the expression builder for the Phone column in the EditCustomers-DT.xlsx workbook's ADF Table component. The expression builder contains an EL expression for the HeaderLabel property of the Phone column that retrieves the value (Phone) defined for an attribute control hint at runtime.

Figure 10-9 EL Expression That Retrieves the Value of an Attribute Control Hint for a Label Property

Attribute control hints can be configured for both view objects and entity objects. Information about how to add an attribute control hint to an entity object can be found in Defining Attribute Control Hints for Entity Objects of Developing Fusion Web Applications with Oracle Application Development Framework. Information about how to define a UI hint for a view object can be found in Defining UI Hints for View Objects of Developing Fusion Web Applications with Oracle Application Development Framework.

An integrated Excel workbook evaluates the Label properties of ADF components when the workbook is initialized after the end user opens the workbook for the first time. The integrated Excel workbook saves the retrieved values for the Label properties when the workbook itself is saved to a directory on the system.

The retrieved values for the Label properties do not get refreshed during invocation of actions such as the worksheet's DownSync action or the ADF Table component's Download action. You indirectly refresh the retrieved values of the Label properties if you invoke the workbook actions ClearAllData or EditOptions described in Table A-18.

1. Open the integrated Excel workbook.
2. In the Workbook group of the Oracle ADF tab, click Workbook Properties.
3. In the Edit Workbook Properties dialog, click the browse (...) icon beside the input field for BrandingItems.
4. In the Edit BrandingItems dialog, click Add and specify values for the new element as follows:

   • Name

     Specify the name, or the EL expression, of the branding item to define.

   • Value

     Specify a literal string or click the browse (...) icon to invoke the expression builder and write an EL expression that retrieves a value at runtime. BrandingItems must use literal strings or resource expressions, and must not contain any binding expression.

   Figure 10-11 shows the design time view of branding items in the Summit sample application for ADF Desktop Integration.

   Figure 10-11 Design Time View of Branding Items in the Summit Sample Application for ADF Desktop Integration

   
   Description of "Figure 10-11 Design Time View of Branding Items in the Summit Sample Application for ADF Desktop Integration"
5. Click OK.

At runtime, the name-value pairs that you define for the BrandingItems group of properties appear in the About tab of the About dialog that the end user invokes using the About ribbon command of the runtime ribbon tab. You configure the runtime ribbon tab to appear, as described in Configuring the Runtime Ribbon Tab. Figure 10-12 shows the runtime view of branding items in an integrated Excel workbook.

Figure 10-12 Runtime View of Branding Items in the Summit Sample Application for ADF Desktop Integration

Description of "Figure 10-12 Runtime View of Branding Items in the Summit Sample Application for ADF Desktop Integration"

1. Open the integrated Excel workbook.
2. If the Table-type component has already been inserted in the Excel worksheet, click any cell of the table, and click Edit Properties in the Oracle ADF tab.

   To insert a Table-type to the worksheet, select the cell where you want to anchor the component. In the components palette or the bindings palette, select the Table-type component or the binding, and click Insert Component or Insert Binding.

3. In the Edit Component: ADF Table dialog, expand the Columns property. Click the browse (...) icon of the Tooltip property of the desired column, and enter the tooltip message. You can enter a literal string or an EL expression.

   Figure 10-14 shows the tooltip EL expression for the ADF Table column header in the Summit sample application's EditCustomers-DT.xlsx workbook that renders the runtime tooltip shown in Figure 10-13.

   Figure 10-14 Tooltip for ADF Table Column Header at Design-time

   
4. Click OK.

1. Open the integrated Excel workbook.
2. If the form-type component has already been inserted in the Excel worksheet, select the component, and click Edit Properties in the Oracle ADF tab.

   To insert a component to the worksheet, select the cell where you want to anchor the component. In the components palette or the bindings palette, select the form-type component or the binding, and click Insert Component or Insert Binding.

3. In the Property Inspector, click the browse (...) icon of the Tooltip property, and enter the tooltip message.

   If a component is created from a binding element, the Tooltip property would be set to the model-driven tooltip. If required, you can configure and change the tooltip message or the EL expression. The property would be empty if the component is not created from a binding element.

   Figure 10-15 shows the Tooltip property of an Input Text component.

   Figure 10-15 Tooltip Property of Input Text Component

   
4. Click OK.

Figure 10-16 shows the tooltip message at the runtime. Notice the small red arrow at the top-right of the Input Text component. It indicates the component, or the cell, has a comment. Hover mouse pointer over the component to see the tooltip message.

Figure 10-16 Tooltip Message of Input Text Component at Runtime

The tooltips for column headers are evaluated and rendered when the table column headers are rendered including first time table initialization, Table.Initialize, and Table.Download actions.

If the Tooltip property of a column is set to a non-empty EL expression, the text that the EL expression evaluates to is trimmed of whitespace, and inserted into the target cell as an Excel comment.

To get a unique tooltip for each expanded dynamic column at runtime, enter the expression in the following syntax in the ToolTip property:

#{bindings.<TreeID>.hints.*.tooltip}

At runtime, the dynamic column expands to the available set of attributes in the specified tree or the node. ADF Desktop Integration also retrieves the corresponding tooltip values and applies each one to the appropriate column using the rules described above.

For information about tooltips, see What You May Need to Know About Tooltips for Form-Type Components. You can also add tooltips to the headers of special columns of the table components (see Special Columns in the ADF Table Component ) and the dynamic columns (see Adding a Dynamic Column to Your ADF Table Component)

1. Open the integrated Excel workbook.
2. In the Workbook group of the Oracle ADF tab, click Worksheet Properties.
3. In the Edit Worksheet Properties dialog, expand the Protection property and configure values as follows:

   • To enable worksheet protection at runtime, set the Mode to Automatic.

   • If desired, provide a value in the Password field. The end user cannot turn off sheet protection at runtime without knowing this value.

     Note that the password is not encrypted and that the maximum password length allowed by Excel is 255 characters. If you specify a longer password, it will be truncated silently at runtime when sheet protection is toggled.

   Figure 10-17 shows the design time view of worksheet protection in the Summit sample application for ADF Desktop Integration.

   Figure 10-17 Design Time View of Worksheet Protection in the Summit Sample Application for ADF Desktop Integration

   
4. Click OK.

At runtime, if the end user tries to edit a read-only cell or a ADF Desktop Integration read-only component, Excel displays the warning message, as shown in Figure 10-18.

Figure 10-18 Worksheet Protection Warning at Runtime

Description of "Figure 10-18 Worksheet Protection Warning at Runtime"

When worksheet protection is enabled, ADF Desktop Integration controls the Locked property for cells that are within the bounds of ADF Desktop Integration components. ADF Desktop Integration does not alter the Locked property of cells outside the bounds of ADF Desktop Integration components.

At runtime, ADF Desktop Integration evaluates the read-only behavior of its components. Some components such as ADF Label and ADF Output Text, are always read-only, and other components, such as ADF Input Text, have a read-only property. At runtime, the Locked property is set to true when read-only for the component evaluates to true. The header labels of ADF Table components are always read-only, but column subcomponents may or may not be read-only depending on their configuration. At runtime, each component's read-only behavior is evaluated and the corresponding cell's Locked property is set to the appropriate value.

Worksheet protection is not enabled by default. You enable it at design time if you want to use it for a particular worksheet. Also, after worksheet protection is enabled, the Locked property for cells is set at runtime.

It is important to note that the password used for worksheet protection is itself not encrypted or stored in a safe location. Worksheet protection is used to improve worksheet usability, not to protect sensitive data.

After worksheet protection is enabled, Excel behaves differently. Here are some differences that you can expect:

• The ADF Table components cannot be sorted, as they include read-only cells in the Key column.

• The end user can insert a full row or column. However, once inserted, they cannot be deleted.

• The end user cannot insert partial rows or columns.

1. Open the integrated Excel Workbook.
2. In the Oracle ADF tab, click Worksheet Properties.
3. Set CustomAttributePropertiesEnabled to True.
4. Click OK.

When a worksheet's CustomAttributePropertiesEnabled is set to True, ADF Desktop Integration EL-based properties start evaluating custom attribute property values returned from the server.

Note the following points about the CustomAttributePropertiesEnabled property and its behavior:

• Custom property names are case-sensitive.

• If the custom property value is itself an EL expression (rather than a literal value), the returned property value gets re-evaluated as EL.

  Note:

  If the custom property value is an EL expression evaluated for a column's ReadOnly property, see Evaluating EL Expressions for ReadOnly Properties for information about evaluating this EL expression.

• EL re-evaluation does not apply to standard attribute hint values.

• When CustomAttributePropertiesEnabled is True, configuration validation does not report a validation error for custom property names in EL.

  When CustomAttributePropertiesEnabled is False, configuration validation does report a validation error for custom property names in EL.

• If a custom property name matches a reserved hint name (for example, label), the custom property is ignored.