About Control Hints for Business Components Clients

Applications that interact with business components rely on the Oracle ADF Business Components technology to access the database. The Business Components tier of this type of data-access application provides mechanisms for retrieving data from the database and converting the database types to Java types for consumption by the client application tier. The Business Component tier also provides a centralized mechanism for any Business Components data item to be rendered in a consistent manner across all client types. This mechanism, known as control hints, permits Business Components developers to:

Centralize certain UI settings across clients and thereby control many aspects of the way the UI interacts with the data item
Reduce the amount of UI coding in the client tier
Permit web page designers to create a customized UI for a particular Business Components project

JDeveloper supports these specific client applications with the built-in capability to interact with the Business Components and utilize control hints:

Databound web components for JSP or ADF UIX applications when the Data Control Palette is registered with Business Components and the Oracle Application Development Framework (Oracle ADF)
Java GUI clients through Oracle ADF JClient

About the Control Hints Mechanism in Business Components

The Business Components tier is an assemblage of cooperative objects which work together to provide a transactional environment for client applications that access the database. Business Components clients interact with the Oracle ADF Business Components technology through the high-level application module object. To initiate database access, the client obtains an instance of the application module, which defines the state of the application data and provides a connection to the database. For each application module, the Business Components developer creates these objects in the Business Components project:

Entity objects to map tables and their columns to the Java object representation
View objects to define the particular usage of the Java object representation for the clients
Attribute objects to define the Java type of a particular data item

In addition to the basic functions these Business Components provide, the Business Components provide numerous other functions that serve the Business Components tier. One of these functions is to store control hint information to define how a client UI should render particular attribute values.

The important point about the usage of control hints in the Business Components project is that control hints are properties of the defining object and as such can be inherited by other Business Components. For example, any control hint property the developer sets on the entity object level will be propagated to any view object that references the entity object. On the other hand, it is also possible to set up control hints at the view object level to override entity-level control hint property definitions. The ability to inherit and override control hint properties by view objects allows the Business Components developer to:

Setup global control hints at the entity object level
Define UI specific control hints at the view object level

About Control Hint Properties

The control hints mechanism supports these control hint properties:

Display Hint determines whether the attribute will be displayed or not. In the JClient design-time wizards, you can override this attribute.

Note: The Data Control Palette does not hide attributes that have this control hint set. It is possible that you may select an attribute for use in your application that will not display at runtime.
Label Text is the text used in prompts or table headers that precede the value of a data item.
Tooltip Text is the text used in tooltips or fly-over text. In Web applications, it appears as the value of the HTML ALT attribute.
Format Type defines the formatter to use when the data item is displayed. Formatters are basically a collection of format masks that you can define in the JDeveloper/system/formatinfo.xml file.
Format is the particular format mask used by the selected formatter.
Control Type selects the control type used to display the data item in the client UI: Edit makes the control editable, Date displays a calendar picker, and default is interpreted by the client to select the most appropriate control.
Display Width defines the character width of the control that displays the data item.
Display Height defines the number of character rows of the control that displays the data item.
Form Type determines whether the attribute will be displayed in Detail mode or Summary mode. The detail mode is a long form, whereas, Summary mode is a short form. This property is supported for JClient applications only; it is not available for Business Components web applications.

About Design-time Support for Control Hints

Design-time support for control hints is provided at two levels:

Editing control hints through property editors
Visualizing control hints in the client through the Visual Editor
Visualizing control hints in the UI of the Business Components Browser

The Business Components design-time wizards provide the mechanisms for setting and editing control hints on the attributes of both entity objects and view objects. To edit controls hints for an attribute, you display the attributes of the desired entity or view object displayed in the Structure window and right-click to open the attribute in the attribute editor.

In the Entity Attribute and View Attribute Editor control hints are visible as properties of the current attribute. You can use the Control Hints tab to easily edit the control hints properties. Once set in the Control Hints tab, you can click the Properties tab to view which hints are added for the attribute.

The following table lists the control hints and whether the various Business Components clients pick them up.

Hint Name	JSP Pages (see note)	ADF UIX Pages	ADF JClient Java UI
Label Text	yes	yes	yes
Tooltip Text	yes	no	yes (see Note2)
Formatter and Format Mask	yes	yes	yes
Display Hint	yes	yes	yes
Control Type	yes	yes	no
Display Width and Height	yes	yes	yes
Form Type	Not applicable.	Not applicable.	yes

Note1: Control hints are not supported on input form pages that rely on the Struts tag libraries and JSTL tags to evaluate expressions. See the following section for details.

Note2: ADF JClient applications ignore any tooltip text that has been entered for an underlying entity object attribute or view object attribute. To workaround this issue you can set the tooltip text in your client code. This example shows how to set the tooltip text for the Deptno attribute:

mDeptno.setToolTipText(panelBinding.findCtrlValueBinding("Deptno").getTooltip());

About Runtime Support for Control Hints

Currently, JSTL tags which appear in a Struts form cannot be used to supply the value for the attribute of another tag. This limitation of JSP 1.2 prevents control hints from being used to set input element's display properties in a Struts input form. For example, currently the following construction is not supported:

<html:text property="EmpName" size='<c:out value="${bindings.EmpName.displayWidth}"/>' />

When working with JSP pages and the ADF bindings, it is possible to specify control hints with HTML tags like this:

<textarea name="<c:out value='${bindings.Dname.path}'/>" cols="<c:out value='${bindings.Dname.displayWidth}' />" rows="<c:out value='${bindings.Dname.displayHeight}' />"> <c:out value='${bindings.Dname}'/> </textarea>

In the case of an ADF UIX page, the date pattern you specify for a UIX component (such as messageDateField) must match the date formatting specified in the control hint. If you don't use the same pattern, you will get a runtime error Cannot create an object of type:oracle.jbo.domain.Date.

Runtime support for control hints is provided at two levels:

Automatically using control hints to render the UI of a Business Components client
Accessing control hint definitions and displaying them through the control hints API

During runtime, Business Components clients automatically make use of the control hints to determine how to render the attribute value. If the control hint property is supported for your particular Business Components client (see above table), no further action is required to customize the UI. Customization of the UI, in this case, takes place in the centralized control hints of the business components themselves.

In the case of JClient (Java UI) clients, the control hints API gives the UI developer direct access to the control hint definitions. Although control hints are properties of the attribute object, it is not recommended to use the getProperty() method to retrieve a particular control hint. Instead, it is recommended to use the convenience methods of the control hints API. For example, the UI developer accesses labels, tooltips, and control types by these methods of the AttributeHints interface:

import oracle.jbo.*

ViewObject vo = am.findViewObject("DeptView"); AttributeDef aDef = vo.findAttribute("DeptNo"); LocaleContext locale = am.getSession().getLocaleContext();

String sLabel = aDef.getUIHelper().getLabel(locale); String sTooltip = aDef.getUIHelper().getTooltip(locale); Int nControlType = aDef.getUIHelper().getControlType(locale);

About the Format Type Control Hint

The formatting control hints Format Type and Format give the Business Components developer the ability to make use of attribute formatters through Business Components domain classes. In the Business Components project, developers can map their formatter to a Business Components domain when they want to:

Define a new formatter in addition to the default Number and Currency formatters
Add an format mask to an existing formatter

Each domain class can have any number of formatters. A formatter can support any number of masks. In the attribute editor, you will be presented with lists of available formatters and their corresponding value masks from which to choose. The mapping of the domain type to its available formatters is maintained in the <jdev_install >/system###/formatinfo.xml file. The Business Components developer uses the Domain wizard to create the domain, but currently JDeveloper does not support autogeneration of domain formatter and masks in the formatinfo.xml file. Developers who create a new domain type and want to add the format to the list of available formatters must hand edit the contents of this file.