Propagating Labels and Tooltips from ADF Data Sources

You can propagate user interface hints such as labels and tooltips, from ADF data sources to display when users work with analyses.

When translated labels and tooltips, based on user locale, are maintained within an ADF data source, you can query the data source to access this translated data. You use the Administration Tool to configure presentation columns to use when creating analyses.

This section contains the following topics:

• What are Labels and Tooltips?

• About the Session Variable Naming Scheme for UI Hints

• About Determining the Physical Column for a Presentation Column

• About Initializing Session Variables Automatically for Propagating UI Hints

• Using UI Hints From an Oracle ADF Data Source When Creating Analyses

• Using XML Code in Initialization Blocks to Query UI Hints

What are Labels and Tooltips?

The propagation of UI hints enables a presentation column in the Oracle BI Administration Tool to use a label and tooltip as its Custom display name and Description respectively.

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 over the item. Each attribute of a view object has an associated label and tooltip. A view object is the Oracle ADF component that enables a developer to work easily with SQL query results.

The image shows the Label Text and Tooltip Text options in the Edit Attribute dialog in JDeveloper.

Description of the illustration GUID-EF6E9E35-4780-47E4-AE8A-DDCB46A1BFA0-default.gif

About the Session Variable Naming Scheme for UI Hints

Learn about the session variable naming scheme.

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

ADF_UI Hint Type_Database Name_View Object 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.

View Object 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 example, in Using XML Code in Initialization Blocks to Query UI Hints, 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

About Determining the Physical Column for a Presentation Column

Each presentation column must map to a physical column as required by the naming scheme for session variables .

When you choose to Generate ADF Labelor or Generate ADF Tooltip for a presentation layer object, the physical column is located using the following rules:

• 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.

• 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.

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

• 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.

• From the remaining ordered list of logical table sources, examine the physical column that is mapped by the first logical table source. A physical column must map to a view object attribute. The physical column must exists as part of a physical database of type Oracle ADF 12c.

  • 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 view object 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 a session variable that has a name based on a predetermined naming scheme. See About the Session Variable Naming Scheme for UI Hints.

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 Using XML Code in Initialization Blocks to Query UI Hints.

About Initializing Session Variables Automatically for Propagating UI Hints

Learn when session variables are created.

If the Generate ADF Label and 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. Variables are created, using Allow deferred execution, and initialized when the variables are needed by a specific query in a session.

When Oracle BI Presentation Services queries the custom display names and custom descriptions through ODBC, the Oracle BI Server checks to determine if the associated session variables have been created. If the variables were not created, the Oracle BI Server dynamically generates the appropriate XML query to retrieve the UI hints from the Oracle ADF data source. The Oracle BI Server uses the UI hints to create and initialize the session variables. To optimize performance, the Oracle BI Server queries UI hints for each view object. If the Oracle BI Server needs the UI hints of a view object's attributes, then the UI hints for all the attributes under the view object are queried and propagated through session variables.

Using UI Hints From an Oracle ADF Data Source When Creating Analyses

You can use UI hints from an Oracle ADF data source when creating analyses.

Before you can perform this task, 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.

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.

Using XML Code in Initialization Blocks to Query UI Hints

As an alternative to using the automated system, 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.

See About the Session Variable Naming Scheme for UI Hints.

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[view_object_name]]></ViewObject>
     <Attribute>
     <ViewObject><![CDATA[attribute_view_object_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 specifies 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.

view_object_name specifies the name of the view object to obtain the UI hints of all attributes in it.

attribute_view_object_name specifies the name of the view object that contains the attribute.

attribute_name specifies the name of the attribute that belongs to the associated view object to obtain the UI hints of this attribute.

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 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. The 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.

   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. 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.

      
      Description of the illustration GUID-5F0C9B6D-4DC9-4154-889A-F38E1C7E709D-default.gif

   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.

Example 6-1 Querying Labels for All View Objects

No child elements must be included in the ADFQuery element, if the UI hints of all attributes in all View Objects are queried. For example, to query the labels of all attributes in all View Objects under the My_orclADF physical database object, use the following XML code:

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

Example 6-2 Querying Tooltips for Specific View Objects

The ADFQuery element can contain zero or more child elements named ViewObject if UI hints of all attributes in specific View Objects are queried. Each ViewObject element has a text content that contains the View Object's name. The ViewObject element is used to specify the View Objects from which the UI hints of all attributes are queried. For example, to query the tooltips of all attributes in the View Object that is named EmployeesView and CustomersView under the My_orclADF physical database object, use the following XML code:

<?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>

Example 6-3 Querying UI Hints for Specific Attributes

The ADFQuery element can contain zero or more child elements named Attribute. Each Attribute element has two required child elements named ViewObject and Name. The Attribute element is used to specify the attributes from which the UI hints are queried. The ViewObject child element has a text content that contains the View Object's name. This element specifies the View Object that the attribute belongs to. The Name child element has a text content which contains the attribute's name. For example, to query the labels and tooltips of the attributes named Firstname and Lastname in the EmployeesView View Object under the My_orclADF physical database object, use the following XML code:

<?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>