Configuring the Appearance of Your Integrated Excel Workbook

About Configuring the Appearance of an Integrated Excel Workbook

Configure the appearance of an integrated Excel workbook using both Excel functionality and Oracle ADF functionality.

Configuring the appearance of a workbook may make the workbook more usable for end users. For example, applying a particular style to cells that render ADF Output Text components at runtime may indicate to end users that the cell is read-only. You may also want to configure the appearance of an integrated Excel workbook so that it aligns with your company's style sheet or the color scheme of the Fusion web application that the Excel workbook integrates with.

Using styles to configure your data in your integrated Excel workbook gives you many benefits. For example, you can use a particular style for ADF Output Text components, and a different style for ADF Input Text components.

ADF Desktop Integration provides several predefined Excel styles to apply to the ADF Desktop Integration components you configure in a workbook. You may want to define additional styles to meet the needs of your desktop integration project. If you do, familiarize yourself with the formats in an Excel workbook that render differently depending on the locale, region, and language.

Integrated Excel Workbook Configuration Use Cases and Examples

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

This image is described in the surrounding text

Additional Functionality for Configuring the Appearance of an Integrated Excel Workbook

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.

Working with Styles

ADF Desktop Integration provides a mechanism to apply Excel-named styles to Oracle ADF components at runtime.

The Oracle ADF components that support the application of styles have properties with StyleName in their name. For example, the column properties of the ADF Table component support the properties HeaderStyleName and CellStyleName that determine styles to apply at runtime.

Predefined Styles in ADF Desktop Integration

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

Tip:

Microsoft Excel has a Merge Styles dialog (accessed from the Styles gallery in the Home runtime ribbon) that allows you to merge all the named styles from one workbook to another workbook.

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.

Excel's Date Formats and Microsoft Windows' Regional and Language Options

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"

Note:

In order for Excel to properly format and manipulate date values with no time component, the form or table attributes must use the java.sql.Date data type in the application's model definition.

How to Apply a Style to an Oracle ADF Component

To apply a style to an Oracle ADF component, use the property inspector to set values for properties with StyleName in their name.

Before you begin:

It may be helpful to have an understanding of styles. See Working with Styles.

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 apply a style:

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.
Select the StyleName property and click the browse (...) icon to display the Edit Expression dialog.
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.
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
Click OK.

What Happens at Runtime: How Style Is Applied to an ADF Component

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

Applying Styles Dynamically Using EL Expressions

Oracle ADF component properties that include StyleName in their name can take an EL expression as a value.

The EL expressions that you write can resolve to a named Excel style at runtime that is applied to the ADF component. The EL expressions that you write are Excel formulas that may include ADF data binding expressions.

The following examples show different contexts where you can use EL expressions to determine the behavior and appearance of ADF components at runtime. Example 10-1 applies a style dynamically during download. If the status value for binding is Closed, apply a read-only style (MyReadOnlyStyle). Otherwise apply another style (MyReadWriteStyle).

Example 10-2 uses a mixture of Excel formulas and ADF binding expressions to handle errors and type conversion. Example 10-3 demonstrates how to use a custom attribute property to specify the style. For information about custom attribute properties, see Using ADF Desktop Integration EL-based Properties with Custom Attribute Properties.

Example 10-1 Applying a Style Dynamically During Download

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

Example 10-2 EL Expressions to Handle Errors and Type Conversion

=IF(ISERROR(VALUE("#{bindings.DealSize}")), "BlackStyle", IF(VALUE("#{bindings.DealSize}") > 300, "RedStyle", "BlackStyle"))

Example 10-3 Using a Custom Attribute Property to Specify the Style

#{bindings.EmpCompView1.hints.EmployeeId.diCellStyle}

What Happens at Runtime: How an EL Expression Is Evaluated

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.

How to Write an EL Expression That Applies a Style at Runtime

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:

Open the integrated Excel workbook.
Select a cell in the Excel worksheet that references the Oracle ADF component for which you want to write an EL expression.
Click the Edit Properties button in the Oracle ADF tab to display the property inspector.
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.

What You May Need to Know About EL Expressions That Apply Styles

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.

Using Labels in an Integrated Excel Workbook

Use labels to provide end users with information about how they use the functionality in an integrated Excel workbook.

You can write EL expressions that retrieve the value of string keys defined in a resource bundle or that retrieve the values of attribute control hints. An integrated Excel workbook evaluates the value of a Label property only when the workbook is initialized.

Retrieving the Values of String Keys from a Resource Bundle

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

Retrieving the Values of Attribute Control Hints

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.

How an Integrated Excel Workbook Evaluates a Label Property

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.

Branding Your Integrated Excel Workbook

ADF Desktop Integration provides several features that you can configure to brand your integrated Excel workbook with information such as application name, version information, and copyright information.

You can use the workbook BrandingItems group of properties to associate this information with an integrated Excel workbook. You must configure a ribbon tab as described in Configuring the Runtime Ribbon Tab so that the end user can view this branding information by clicking a ribbon command that invokes the ViewAboutDialog workbook action at runtime. See Table A-18.

ADF Desktop Integration also provides a style (Branding Area) to assist you in branding your integrated Excel workbooks. The ADF Desktop Integration sample application applies this style to the first row of each of its sample workbooks. Used with the ADF Image and ADF Output components, as demonstrated in Figure 10-10, the style contributes to the consistent branding of the integrated Excel workbooks in the sample application.

Figure 10-10 Branding Area in Sample Workbook

Description of "Figure 10-10 Branding Area in Sample Workbook"

You can also define string keys in a resource bundle to define information, such as titles, in one location that can then be used in multiple locations in an integrated Excel workbook at runtime when EL expressions retrieve the values of these string keys. For information about defining string keys, see Using Resource Bundles in an Integrated Excel Workbook.

How to Brand an Integrated Excel Workbook

You define values for the workbook BrandingItems group of properties.

Before you begin:

It may be helpful to have an understanding of how to customize the brand of your integrated Excel workbook. See Branding Your Integrated Excel Workbook.

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 brand an integrated Excel workbook:

Open the integrated Excel workbook.
In the Workbook group of the Oracle ADF tab, click Workbook Properties.
In the Edit Workbook Properties dialog, click the browse (...) icon beside the input field for BrandingItems.
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"
Click OK.

Tip:

You may also add your brand's image or logo to the integrated Excel spreadsheets. See Inserting an ADF Image Component.

What Happens at Runtime: the BrandingItems Group of Properties

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"

Note:

No About tab appears in the About dialog at runtime if you do not specify properties for the BrandingItems group of workbook properties.

Displaying Tooltips in ADF Desktop Integration Components

Use tooltips to display a hint or instruction text for ADF Desktop Integration components and table column headers. The tooltip appears in the Comment window of the cell that anchors the component or in the column header cell in the case of table column headers.

Tooltips can be defined as literal strings or EL expressions. You enter the literal string in the Tooltip property of the component or the column. You can also specify the EL expression (including a resource expression) as a value for the Tooltip property. At runtime, the EL expression resolves to the tooltip to display.

Note:

ADF Desktop Integration also supports toolTip attribute control hint in EL expressions. The support is similar to the mandatory control hint described in Table B-3 of ADF Desktop Integration EL Expressions.

If you create a component from a binding element, the tooltip is automatically set to the model-driven tooltip, otherwise it is empty. Note that the tooltip is always initially empty for the ADF Label component. For table column headers, the default value that it renders is the value of the Fusion web application's attribute control Tooltip property, as shown in Figure 10-13, if you created the ADF Table component from a tree binding. The Special columns (Changed, Flagged, Status) are an exception. By default, they do not render a tooltip.

Attribute control hints can be configured for view objects. 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. For information about how to retrieve the value of an attribute control hint in an integrated Excel workbook, see Retrieving the Values of Attribute Control Hints.

For information, see How to Add a Tool Tip to an ADF Table Component and How to Add a Tool Tip to a Form-Type Component.

Figure 10-13 Attribute Control Hint Tooltip that Renders Tooltip in ADF Table Column Header

Description of "Figure 10-13 Attribute Control Hint Tooltip that Renders Tooltip in ADF Table Column Header"

Note:

In Figure 10-13, notice the small red arrow at the top-right of the Zip Code column header cell in the EditCustomers-DT.xlsx workbook. It indicates that the header cell has a comment. Hover your mouse pointer over the cell to see the tooltip message.

How to Add a Tool Tip to an ADF Table Component

You configure the Tooltip property of the column in the ADF Table component that you want to render a tooltip.

Before you begin:

It may be helpful to have an understanding of tooltips. See Displaying Tooltips in ADF Desktop Integration 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 Configuring the Appearance of an Integrated Excel Workbook.

To add a tooltip to a table column header:

Open the integrated Excel workbook.
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.
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
Click OK.

How to Add a Tool Tip to a Form-Type Component

You configure the Tooltip property of component that you want to render a tooltip.

Before you begin:

It may be helpful to have an understanding of tooltips. See Displaying Tooltips in ADF Desktop Integration 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 Configuring the Appearance of an Integrated Excel Workbook.

To add a tooltip to an inserted form-type component:

Open the integrated Excel workbook.
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.
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
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

What You May Need to Know About Tooltips for Form-Type Components

The tooltips are rendered once only, and are not updated after a call to Worksheet.DownSync.

Any Excel comment added manually at design time to a cell (or merged area) containing an ADF component is removed at runtime and replaced by the ADF component's tooltip. Similarly, any Excel comment added manually to an ADF component's cell during test mode is removed when the integrated Excel workbook returns to design-time mode. Excel comments added to cells with no ADF components, or to ADF components that do not support tooltips remain unchanged.

At runtime, if the Tooltip property is non-empty, the expression is evaluated and the resulting text is trimmed of whitespace. If the final value is non-empty, it is inserted into the target cell as an Excel comment.

When a component is positioned on a merged range of cells, the tooltip appears on the top-right corner of the merged range.

You can also add tooltips to table columns (see What You May Need to Know About Tooltips for Table Columns) and Worksheet Ribbon commands (see How to Configure a Worksheet Ribbon Command for the Runtime Ribbon Tab).

Note:

Tooltips are not editable in a protected worksheet.
Ribbon command tooltips have a maximum size of 1024 characters. If a tooltip value exceeds that limit, only the first 1024 characters are shown.
If Excel Comments are disabled, tooltips for form components and table headers are not rendered.
Extensive usage of tooltips may impact runtime performance.

What You May Need to Know About Tooltips for Table Columns

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)

Using Worksheet Protection

By default, end users can edit the values of locked cells and ADF Desktop Integration components that have implied read-only behavior, such as ADF Label, ADF Output Text and ADF Table component's header rows, at runtime.

While uploading data, ADF Desktop Integration ignores these changes and overwrites them when it next refreshes the component.

Various ADF Desktop Integration components, (for example, ADF InputText component) and subcomponents (for example, ModelDrivenColumnComponent subcomponent) include a ReadOnly property.

To prevent editing of locked cells at runtime, enable ADF Desktop Integration worksheet protection. Optionally, you can also provide a password to prevent the end user from turning off worksheet protection.

Do not use the Excel's Protect Sheet or Protect Workbook features directly in an integrated Excel workbook. Also, ensure that end users do not use these features.

How to Enable Worksheet Protection

Worksheet protection enables true read-only mode for locked and read-only cells, and prevents any editing at runtime.

Before you begin:

It may be helpful to have an understanding worksheet protection. See Using Worksheet Protection.

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 enable Worksheet Protection:

Open the integrated Excel workbook.
In the Workbook group of the Oracle ADF tab, click Worksheet Properties.
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
Click OK.

What Happens at Runtime: How the Locked Property Works

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.

What You May Need to Know About Worksheet Protection

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.

Using ADF Desktop Integration EL-based Properties with Custom Attribute Properties

You can use custom attribute properties defined in view objects on the server with ADF Desktop Integration EL-based properties of the integrated Excel workbook. By default, ADF Desktop Integration EL evaluation does not support custom attribute properties defined on the server.

To enable the support, you must set the Worksheet.CustomAttributePropertiesEnabled property to True.

After enabling the support, you can reference custom attribute property names in EL-based property values.

How to Enable Custom Attribute Properties in Integrated Excel Workbook

Before you enable custom attribute properties, configure one (or more) custom attribute properties in your Fusion web application. For information about how to define a UI hint for a view object, see Defining UI Hints for View Objects in Developing Fusion Web Applications with Oracle Application Development Framework.

To enable custom attribute properties in integrated Excel workbook:

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

After setting CustomAttributePropertiesEnabled to True, you can reference custom attribute properties within EL expressions using one of the following formats:

For attribute hint, use this format: "#{bindings.{attr id}.hints.{custom property}}"
For tree attribute hint, use this format: "#{bindings.{tree id}.hints.{attr id}.{custom property}}"
For dynamic column hint, use this format: "#{bindings.{tree id}.[{node id}].hints.*.{custom property}}"

In the following examples, diCellStyle is a custom attribute property that the developer added to the relevant model attribute:

static column example: #{bindings.EmpCompView1.hints.EmployeeId.diCellStyle}
dynamic column example: #{bindings.EmpCompDeclSqlView1.[model.EmpCompDeclSqlView].hints.*.diCellStyle}

What Happens at Runtime: CustomAttributePropertiesEnabled is Set to True

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.

Tip:

For best performance, whenever possible, ensure that the custom property value should be a literal value (for example: an Excel style name).

What You May Need to Know About the CustomAttributePropertiesEnabled Property

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.