Propagate Labels and Tooltips from ADF Data Sources

What Are Labels and Tooltips?

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

A label is the text that's used in prompts or table headers that precedes the value of a data item. A tooltip is the text that's 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 hintsjdev.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 Analytics Server 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 a LABEL or TOOLTIP.

Database Name is the value for 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 attribute of the view object. Oracle ADF prohibits special characters and spaces in the name.

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

Every character in the session variable name is uppercase. The XML query example, in Use 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 Label 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 can't be found.
If the default aggregation rule for the logical column isn't None or Sum, then the physical column can't be found. It doesn't 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 aren't disabled are searched.
Don't 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 can't be found.
From the remaining ordered list of logical table sources, examine the physical column that's mapped by the first logical table source. A physical column must map to a view object attribute. The physical column must exist 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 isn't satisfied, then continue to examine the physical column that's mapped by the next logical table source until the physical column that's mapped to a view object attribute is found.
  
  If all logical table source are searched without satisfying the condition, then the physical column can't 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 isn't 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 Use 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 aren't created and initialized during the session logon stage for performance reasons. Variables are created, using Allow deferred processing, 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 weren't 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.

Use 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 Model Administration Tool.

Right-click the column in the Presentation layer and select Externalize Display Names, select Generate ADF Label, select Externalize Descriptions, and then select Generate ADF Tooltip to generate tooltip strings for all of the columns.

Use XML Code in Initialization Blocks to Query UI Hints

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.

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 Use UI Hints from an Oracle ADF Data Source When Creating Analyses, but replace the first step with the following ones:

Create session initialization blocks in the Model Administration Tool, see Create Session Variables.

In the Session Variable Initialization Block Data Source dialog, enter the Initialization string.
In the Session Variable Initialization Block dialog, from the Variable Target list, select Row-wise initialization.
Click Test to test the query against the Oracle ADF data source.
Configure a custom display name and write a description in presentation columns.
Right-click a physical table, select Query Related Objects, select Presentation, and then select Presentation Table.
In Query Related Objects, select the required presentation table and click Go To.
Expand the presentation table to view the presentation columns.
Double-click the presentation column to display the Presentation Column dialog.
Select Custom display name and enter a value similar to the following:
```
VALUEOF(NQ_SESSION.ADF_LABEL_MY_ORCLADF_EMPLOYEESVIEW_LASTNAME)
```
Select Custom description and enter a value similar to the following:
VALUEOF(NQ_SESSION.ADF_TOOLTIP_MY_ORCLADF_EMPLOYEESVIEW_LASTNAME)
Click OK.
Save the changes in the repository and restart the Oracle BI Server.

ADFQuery Element Reference

Use the ADFQuery element and its mode, database, and locale attributes in your XML code.

The element requires zero or more child elements. The following is the syntax of the element:

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

Querying Labels for All View Objects

Don't include child elements in the ADFQuery element when querying the UI hints of all attributes in all View Objects. 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>

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's 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>

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>