F Propagating Labels and Tooltips from Oracle ADF Data Sources

F.1 What are Labels and Tooltips?

A label is the text that is used in prompts or table headers that precedes the value of a data item. A tooltip is the text that is displayed when a user hovers the mouse pointer over the item. Each attribute of a view object (VO) has an associated label and tooltip. A view object is the Oracle Application Development Framework component that enables a developer to work easily with SQL query results. The propagation of UI hints enables a presentation column in the Administration Tool to use a label and tooltip as its Custom display name and Description respectively.

Figure F-1 shows the Label Text and Tooltip Text options in the Edit Attribute dialog in Oracle JDeveloper.

Figure F-1 Edit Attribute Dialog Box in JDeveloper for Label and Tooltip Options

Description of "Figure F-1 Edit Attribute Dialog Box in JDeveloper for Label and Tooltip Options"

F.2 Session Variable Naming Scheme for UI Hints from an Oracle ADF Data Source

Session variable names are generated by the Oracle BI Enterprise Edition broker servlet in Oracle WebLogic Server in the following format:

ADF_UI Hint Type_Database Name_VO's Name_Attribute's Name

Where:

UI Hint Type is either LABEL or TOOLTIP, depending on the UI hint type that the session variable represents.

Database Name is the value of the "database" attribute of the ADFQuery element in the XML query. Special characters such single quotes ('), double quotes ("), and spaces are replaced by the underscore character.

VO's Name is the name of the View Object to which the attribute belongs. Oracle ADF prohibits special characters and spaces in the name.

Attribute's Name is the name of the attribute that the session variable represents. Oracle ADF prohibits special characters and spaces in the name.

Every character in the session variable name is uppercase. For example, the XML query in Example F-3 generates four session variables with the following names:

ADF_LABEL_MY_ORCLADF_EMPLOYEESVIEW_FIRSTNAME

ADF_TOOLTIP_MY_ORCLADF_EMPLOYEESVIEW_FIRSTNAME

ADF_LABEL_MY_ORCLADF_EMPLOYEESVIEW_LASTNAME

ADF_TOOLTIP_MY_ORCLADF_EMPLOYEESVIEW_LASTNAME

F.3 Mapping of Presentation Columns to Physical Columns

As required by the naming scheme for session variables, each presentation column must map to a physical column. When you select Externalize Display Names > Generate ADF Label or Externalize Descriptions > Generate ADF Tooltip for a presentation layer object, then the physical column is located using the following rules:

1. Examine the presentation column and determine its logical column. If the logical column is derived from an existing logical column, then the physical column cannot be found.

2. If the default aggregation rule for the logical column is not None or Sum, then the physical column cannot be found. It does not make sense semantically to use the ADF UI hints for aggregation rules other than Sum.

3. A logical column can be mapped to physical columns by multiple logical table sources. Only logical table sources that are not disabled are searched.

4. Do not search logical table sources that map the logical column using non-trivial expressions (that is, anything more than a physical column name). If no logical table sources are searched, then the physical column cannot be found.

5. From the remaining ordered list of logical table sources, examine the physical column that is mapped by the first logical table source. The physical column must be mapped to a VO attribute. In other words the physical column must be part of a physical database of type OracleADF11g.

   • If this condition is satisfied, then the physical column for obtaining UI hints is found.

   • If this condition is not satisfied, then continue to examine the physical column that is mapped by the next logical table source until the physical column that is mapped to a VO attribute is found.

     If all logical table source are searched without satisfying the condition, then the physical column cannot be found.

If the physical column for obtaining UI hints is found using these rules, then the custom display name or description is populated with the session variable whose name is based on the scheme that is described in Section F.2, "Session Variable Naming Scheme for UI Hints from an Oracle ADF Data Source."

If the physical column for obtaining UI hints is not found using these rules, then the Generate ADF Label and Generate ADF Tooltip options are shown as disabled in the right-click menu.

As an alternative to using the physical column found using these rules, you can use XML code in an initialization block to initialize your own session variables with ADF UI hints. You must then enter these session variable names in the Custom display name and Custom description fields manually. See Section F.6, "Using XML Code in Initialization Blocks to Query UI Hints from an Oracle ADF Data Source" for more information.

F.4 Initializing Session Variables Automatically for Propagating UI Hints

If the Externalize Display Names > Generate ADF Label and Externalize Descriptions > Generate ADF Tooltip options were used to successfully generate the session variable names for UI hints from Oracle ADF, then the session variables are created and initialized when Oracle BI Presentation Services queries them during the session. The variables are not created and initialized during the session logon stage for performance reasons. Instead, the variables are created and initialized when they are needed by a specific query within a session, using the Allow deferred execution feature.

When Presentation Services queries the custom display names and custom descriptions through ODBC, the Oracle BI Server checks if the associated session variables have been created. If they have not been created, then the BI Server dynamically generates the appropriate XML query (as described in Section F.6, "Using XML Code in Initialization Blocks to Query UI Hints from an Oracle ADF Data Source") to query the UI hints from the Oracle ADF data source. The BI Server uses the UI hints to create and initialize the session variables. As an optimization, the BI Server queries UI hints per VO; that is, if the BI Server needs the UI hints of a VO's attributes, then the UI hints for all the attributes under the VO are queried and propagated through session variables.

F.5 Example: Using UI Hints From an Oracle ADF Data Source When Creating Analyses

The following example shows how you can use UI hints from an Oracle ADF data source when creating analyses.

The following prerequisites must be met:

• UI hints must have been configured in the Oracle ADF data source.

• A working repository must have been configured for the Oracle ADF data source in the Administration Tool.

To use UI hints from an Oracle ADF data source when creating analyses:

1. Suppose that the repository contains a presentation column named "LastName." On the General tab of the Presentation Column dialog, the Custom display name and Custom description fields are not selected.

   Right-click the column in the Presentation layer and select first Externalize Display Names > Generate ADF Label, then Externalize Descriptions > Generate ADF Tooltip to generate the strings that populate the Custom display name and Custom description fields.

   You can also use these options from the right-click menu of a presentation table to generate the strings for all the columns in that table.

2. View the UI hints:

   1. Sign in to Oracle Business Intelligence.

   2. Create a new analysis using the subject area for which you obtained UI hints.

   3. In the Subject Areas pane, expand the Employee folder to see the UI hints that have been propagated from the Oracle ADF data source.

      The LastName column displays as "Last Name" (the label value from the Oracle ADF data source). When you hover the mouse pointer over the column, the tip displays as "This is the employee's last name" (the tooltip value from the Oracle ADF data source).

   For information about creating analyses, see Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.

F.6 Using XML Code in Initialization Blocks to Query UI Hints from an Oracle ADF Data Source

As an alternative to using the automated system described in the previous section, you can use specialized XML code in place of SQL statements in initialization blocks to query the data source for UI hints, within a single repository and subject area. You use the ADFQuery element, which has three attributes that are named mode, database, and locale. The element requires zero or more child elements. The syntax of the element is as follows:

<?xml version="1.0" encoding="iso-8859-1" standalone="yes"?>
<ADFQuery mode="{Mode}" database="{Database Name}"
locale="VALUEOF(NQ_SESSION.WEBLANGUAGE)">
     <ViewObject><![CDATA[{VO Name}]]></ViewObject>
     <Attribute>
     <ViewObject><![CDATA[{Attribute VO Name}]]></ViewObject>
     <Name><![CDATA[{Attribute Name}]]></Name>
     </Attribute>
</ADFQuery>

where

{Mode} specifies what you want to query:

• label for querying attributes' label

• tooltip for querying attributes' tooltip

• ui_hints for querying attributes' label and tooltip

{Database Name}

Use the name of the physical database object in the Administration Tool, which contains the physical columns that correspond to the attributes in the Oracle ADF data source.

{VO Name}

Use the name of the View Object to obtain the UI hints of all attributes in it.

{Attribute VO Name}

Use the name of the View Object that contains the attribute.

{Attribute Name}

Use the name of the attribute that belongs to the associated View Object to obtain the UI hints of this attribute.

<?xml version="1.0" encoding="iso-8859-1" standalone="yes"?>
<ADFQuery mode="label" database="My_orclADF"
locale="VALUEOF(NQ_SESSION.WEBLANGUAGE)">
</ADFQuery>

<?xml version="1.0" encoding="iso-8859-1" standalone="yes"?>
<ADFQuery mode="tooltip" database="My_orclADF"
locale="VALUEOF(NQ_SESSION.WEBLANGUAGE)">
   <ViewObject><![CDATA[EmployeesView]]></ViewObject>
   <ViewObject><![CDATA[CustomersView]]></ViewObject>
</ADFQuery>

<?xml version="1.0" encoding="iso-8859-1" standalone="yes"?>
<ADFQuery mode="ui_hints" database="My_orclADF"
locale="VALUEOF(NQ_SESSION.WEBLANGUAGE)">
   <Attribute>
      <ViewObject><![CDATA[EmployeesView]]></ViewObject>
      <Name><![CDATA[Firstname]]></Name>
   </Attribute>
   <Attribute>
      <ViewObject><![CDATA[EmployeesView]]></ViewObject>
      <Name><![CDATA[Lastname]]></Name>
   </Attribute>
</ADFQuery>

After configuring the initialization blocks, you must manually enter the session variable names in the Custom display name and Custom description text fields for the appropriate presentation column.

Follow the procedure in the example in Section F.5, "Example: Using UI Hints From an Oracle ADF Data Source When Creating Analyses", but replace the first step with the following ones:

1. Create session initialization blocks in the Administration Tool.

   1. In the Session Variable Initialization Block Data Source dialog, enter the Initialization string.

      In this example, the initialization block queries both the label and tooltip of all attributes in a View Object named EmployeesView. Figure F-2 shows the setup of a session variable initialization block with an appropriate Oracle ADF UI hint query. "My_orclADF"."Connection Pool" is a connection pool for an Oracle ADF data source.

      Figure F-2 Setup of a Session Variable Initialization Block Data Source with an Oracle ADF UI Hints Query

      
      Description of "Figure F-2 Setup of a Session Variable Initialization Block Data Source with an Oracle ADF UI Hints Query"
      
      

   2. In the Session Variable Initialization Block dialog, select Row-wise initialization as the Variable Target.

   3. Click Test to test the query against the Oracle ADF data source.

      In the results window, the first column contains the session variable names that are generated using the naming scheme that is described in Section F.2, "Session Variable Naming Scheme for UI Hints from an Oracle ADF Data Source." The second column contains the label and tooltip values from the Oracle ADF data source.

2. Configure a custom display name and a description in presentation columns.

   To find the presentation tables that can use the UI hints from the EmployeesView View Object, this example uses the Query Repository feature in the Administration Tool.

   1. Right-click a physical table (for example, EmployeesView), then select Query Related Objects > Presentation > Presentation Table from the menu.

      The Query Related Objects dialog displays all the related presentation tables.

      This example sets up a custom display name and custom description for columns in the Employee presentation table.

      Figure F-3 Using the Query Related Objects Feature to Find the Related Presentation Tables

      
      Description of "Figure F-3 Using the Query Related Objects Feature to Find the Related Presentation Tables"
      
      

   2. Select the required presentation table and click Go To.

      This displays the selected presentation table.

   3. Expand the presentation table to view the presentation columns.

   4. Double-click the LastName presentation column to display the Presentation Column dialog.

   5. Select Custom display name and enter a value such as the following one:

      VALUEOF(NQ_SESSION.ADF_LABEL_MY_ORCLADF_EMPLOYEESVIEW_LASTNAME)
      

   6. Select Custom description and enter a value such as the following one:

      VALUEOF(NQ_SESSION.ADF_TOOLTIP_MY_ORCLADF_EMPLOYEESVIEW_LASTNAME)
      

   7. Click OK.

   8. Save the changes in the repository and restart the Oracle BI Server.