Understanding UI Hints

A schema may be used to describe the structure of a business object or any other XML document. When applicable, the same schema may also embed user interface (UI) "hints" that are interpreted at run time and render the HTML needed to display or maintain that document. Refer to UI Hint Syntax for more information.

The main advantages of this technique are as follows:
  • Less error prone. A tighter correlation between the data structure and its presentation layer keeps the latter up to date, for example:
    • Adding an element to the schema or removing an element from it result in a corresponding change to the presentation layer. Note that you can explicitly exclude elements from the presentation layer as needed.
    • The HTML widget that is most appropriate to present or input data for an element is determined by its data type as defined by the schema. For example, a date picker is used for an input date element. If the element's data type changes in the schema its presentation adjusts accordingly.
  • Faster to implement. No HTML skills are needed. The schema definition along with its embedded UI hint instructions is used to render the HTML at run time. Eliminating the need of crafting HTML and maintaining it as a UI Map reduces implementation and maintenance costs.
  • Supports business object inheritance. Incorporating the presentation layer into the business object schema allows each business object in a hierarchy to contribute their part to the complete HTML that displays the entity. In other words, the complete HTML used to display a subclassed business object is made of the HTML rendered by the included schema of its parent business object, followed by elements extended by the subclass.

The topics in this section describe concepts and guidance relevant to the UI Hints functionality.

Display vs. Input Modes

The same schema may be used to generate either a display version of its HTML map or an input map. In the display version, element values are presented as read-only, corresponding descriptions are shown instead of codes, and additional artifacts such as links are available for navigation to related pages. In the input version, the element is editable, using the appropriate HTML widget for its data type. For example, a foreign key element is rendered along with search components, and a date element incudes a date picker widget.

The type of map generated depends on the context in which it is used:
  • The display map is generated when the schema is used to present content in a map zone.
  • The input map is generated when the schema is used for data entry as part of a BPA script step or a process flow panel. Refer to Generate Edit Map Statements and process flows for more information.

By default, each element in the schema is assumed to be included in both the display and input presentation maps. UI hints allow an element to be excluded from presentation altogether, included only in the display map or included only in the input map.

Not Just Business Object Schemas

While mostly used to describe the display and maintenance maps of business objects, UI Hints may also be embedded as part of other schema based objects:
  • You may use a data area to describe an input form and prompt the user to fill it in using a BPA script step or a process flow panel.
  • You may embed UI hints in a business service or service script schema for the purpose of displaying the content prepared by the service in a portal zone. Refer to map zones for more information.
  • You may embed UI hints in a service script's schema to prompt for user input before calling the script to perform a task and presenting results. Refer to Generate Edit Map Statements for more information.

Definition Order is Presentation Order

Elements are presented in the order they are defined in the expanded schema. For example, a subclassed business object that includes its parent business object followed by extension elements is presented with the parent portion of the HTML, followed by the extension fields.

Use UI Map Fragments for Complex HTML

The following items describe basic capabilities supported by the UI Hints functionality:
  • Control which elements are presented in the display and input maps.
  • Provide a title for the input map.
  • Introduce sections around elements by injecting start and end section instructions. The order in which the elements are defined within a section is also their presentation order.
  • Basic visibility rules are supported at the element and section level.
For more complex requirements around a specific element, you may craft the necessary HTML/JavaScript for the element, capture it as a UI Map Fragment, embed the fragment as part of the schema in the appropriate presentation order, and suppress the element from basic rendering for the corresponding input or display map.
Note: You may also use this technique to display elements in a different presentation location. For example, when a business object's display script needs to display additional elements that are not part of the business object's schema. In this situation, the script's schema introduces the elements as suppressed and the business object schema includes an embedded HTML UI map fragment to display them in the appropriate section. Note that this may only work when both the business object and script are owned by your organization.

Refer to UI Hint Syntax for more information.