UI Hint Syntax

Working Examples

For working examples of uiHint functionality, refer to the following business objects:

BOs with User Assigned Keys

The following examples illustrate the patterns used to enable uiHints on an object with a user specified key.

F1-OutcomeStyleLookup. This extendable lookup BO does not require state transition, but does allow duplicate and delete actions.
F1-TodoSumEmailTyp. This request type illustrates the hints required to support state transition on a display map.
F1-WebSvc. This web service BO is a good example for management of complex JavaScript requirements. Both display and input maps have functionality that requires specialized javascript.

BO with System Generated Key

The following example illustrates the pattern used to enable uiHints on an object with a system generated key.

F1-GenericAttachment. This attachment BO has a system assigned key, which entails the following special handling:
- F1-AttachmentMain. This is the main section data area contains the elements common to all attachments, including the key, bo, and version. Because this data area is used to define the main section of the generated maps, the main section of the map can be extended by an implementation via data area extension functionality.
- F1-AttachmentActions. This record actions map contains the standard actions, Edit and Delete, plus custom actions used only by attachments, View and Upload.
- F1-AttachmentIDFrag. This record information map contains the primary key of the attachment.

Display Map Service Script

Display map service scripts can be fully supported via dynamic HTML generation. However, to help eliminate the need for a display service script, self-contained uiHint functionality has been developed to write the business object status and determine valid state transitions. So the two most common reasons to craft a display service script have been eliminated.

A typical reason to use a display pre-script is if you have an embedded map fragment that contains a business service schema. The display service script can be used to invoke the business service. Both the map fragment and the display service script must declare the business service schema to support this scenario.

Warning: The zone used to display the object's map must have a derivation script, like F1-GncDsMpDZ or F1-GenDss, that will invoke a display service script for the business object if it has been defined as a BO option - but not require an explicit display map BO option. In addition, the display service script's schema must be enabled for uiHint functionality - as the script's schema will be dynamically rendered by the zone - and not the BO schema.

F1-ExcelSpreadsheet. This attachment BO has a display service script used to manipulate the attachment business object before displaying it:
F1-AttchDtlU. This display map service script's schema has been defined with the uiHint namespace, and will have a display map generated for it.

Maintenance Pre-Processing Service Script

Maintenance pre-processing service scripts can be used with uiHints.

F1-ExcelSpreadsheet. This attachment BO has a maintenance pre-processing service script used to manipulate the attachment business object before rendering the maintenance map:
F1-AttchPre. This pre-processing service script's schema mimics a maintenance map schema with embedded boGroup and action elements. It will be invoked before the maintenance map is rendered.

Maintenance Post-Processing Service Script

Maintenance post-processing service scripts can be used with uiHints.

F1-ExcelSpreadsheet. This attachment BO has a maintenance post-processing service script used to manipulate the attachment business object after rendering the maintenance map:
F1-AttchPost. This post-processing service script's schema mimics a maintenance map schema with embedded boGroup and action elements. It will be invoked after the maintenance map is rendered.

Technical Notes

The following prerequisites are required to support dynamic HTML generation:

Schema Requirements

To support automated UI generation, the business object schema must contain the following:

<schema xmlns:uiHint="http://oracle.com/ouafUIHints">. The schema node must name the uiHint namespace.
isPrimeKey="true". Every element of the business object schema that is part of the primary key must be identified.

Maintenance Script Requirements

The maintenance script for the MO must be enabled for dynamic generation.

CAUTION: The business object maintenance BPA script must be declared as an MO Option for uiHint maintenance functionality to work!

If the script performs F1-BOProc then it is likely no special functionality is needed. However, if the maintenance script contains its own call to F1-GetValOpt then the following statement is required prior to that call:

move 'false' to "F1-GetBOOpts/input/maintenanceMapRequired";
performScript 'F1-GetValOpt';

After the call to F1-GetValOpt the following logic must be included to dynamically declare the map schema if the business object does not have a maintenance map of its own:

 // Perform Main Processing
if ("F1-GetBOOpts/output/maintenanceMap = $BLANK")
  declareBOWithBOGroup "$bo" as 'map_schema';
else
  declareMap "F1-GetBOOpts/output/maintenanceMap" as 'map_schema';
end-if;

Format an Input Map Title

Note: Throughout this topic the term "field" to refer to both the generic concept of displaying and capturing data in a 'field' as well as referring to the meta-data object supplied in the product to define Fields. When referring to the latter, the term "MD Field" (meta-data Field) is used.

A uiHint element can be used to build a title for a maintenance map. The title will only print on the maintenance map, not on the display map. It will be printed as the first line in the map, centered, with a heading style.


Syntax	Description	Examples
<uiHint:title mdField=" "/>	Displays the label of a referenced MD field as the title.	`<schema xmlns:uiHint="http://oracle.com/ouafUIHints"> <uiHint:title mdField="STATUS_RSN_LBL"/> ... </schema>`
<uiHint:title text=" "/>	Displays the indicated text as the title. (Do not use this mechanism when multiple languages are supported.	`<schema xmlns:uiHint="http://oracle.com/ouafUIHints"> <uiHint:title text="Status Reason"/> ... </schema>`

Create a Section

The uiHint namespace supports the definition of a UI map section. Note that sections are currently created in generated UI Maps when the schema has a group or list node with a label or mdField. The functionality described here enables the creation of a section without requiring a labeled group or list node within the schema. Every section must be bounded by startSection and endSection element pair.


Syntax	Supporting Attributes	Description
<uiHint:startSection .../>	sectionColumn="left \| right \| fullWidth \| float"	The default is that the section will be the full width in display maps. To override that setting, specify if you want a half-width section to appear in either the left (left) or right (right) column or to float (float). Sections that are marked as 'float' will display half-width and be aligned according to whether prior sections are displayed or conditionally hidden. For example, if a left-aligned section is followed by a floating section, the floating section will appear in the right column if the left section is populated but will display in the left column if the left section is hidden / collapsed.
	editColumn="left \| right \| fullWidth \| float"	By default a section appears as full width in maintenance maps. To override that setting, specify if you want a half-width section to appear in either the left (left) or right (right) column or to float (float). The behavior is the analogous to the sectionColumn behavior.
	sectionOpen="false"	By default a section is open on initial display. Specify this attribute to initially display the section as closed (collapsed).
	mdField=" "	Specify the name of a MD field whose label should be used as the section heading.
	label=" "	Specify the explicit text to use as the section heading.
	visibleOn="displayMap \| inputMap"	By default a section appears on both the display and the input maps. Use this attribute to limit the display of the section to either the display map (displayMap) or input map (inputMap).

The syntax for the end section attribute is <uiHint:endSection/>

Examples:

<schema xmlns:uiHint="http://oracle.com/ouafUIHints">
    <uiHint:startSection label="Main" sectionColumn="left"/>
    ...
    <uiHint:endSection/>
</schema>

<schema xmlns:uiHint="http://oracle.com/ouafUIHints">
    <uiHint:startSection mdField="F1-ADD-INFO" sectionColumn="fullWidth" editColumn="float" sectionOpen="false" visibleOn="displayMap"/>
    ...
    <uiHint:endSection/>
</schema>

Note: The sectionColumn, editColumn and sectionOpen attributes are available for group and list nodes as well.

Include a Map Fragment

You can specify a UI map fragment to inject HTML into a generated map using the includeMap element name. This allows for you to support more sophisticated behavior on your user interface. For any element that is included for rendering in the map fragment, be sure to suppress the element in its schema definition, otherwise HTML will automatically be generated for the element.


Syntax	Supporting Attributes	Description
<uiHint:includeMap .../>	map=" "	Specify the name of the map.
<uiHint:includeMap .../>	visibleOn="displayMap \| inputMap"	By default the details from the map fragment appear on both the display and the input maps. Use this attribute to limit the display of the section.

Example:

<schema xmlns:uiHint="http://oracle.com/ouafUIHints">
  ...
  <uiHint:includeMap map="StandardActionButtons" visibleOn="displayMap"/>
  ...
</schema>

Note: Important note on the map fragment schema: If a map fragment contains a schema, then the fragment schema structure will be injected into the dynamically generated schema when the business object is rendered for input. Technically, the fragment schema will be inserted after the boGroup structure within the map's schema. This method may be used to support the implementation of maintenance pre and post script processing for a business object and oraInvokeBS function calls within embedded JavaScript.

If JavaScript is required within an XHTML UI Map fragment, it is necessary to bound it within a ![CDATA[ ]] tag to ensure a valid XML document. Note that the tags themselves may need to be commented out to promote compatibility with older browsers. For example:

		<script type="text/javascript">
/* <![CDATA[ */
//
//javascript
//
/* ]]> */
</script>

Flush the cache: For performance reasons, the Framework automatically caches business object schemas, data areas, and UI maps. When you update a business object, the cache is automatically flushed. However, if the business object includes either a data area or embedded UI map fragment, the cache must be manually flushed in order for your changes to be recognized. Refer to Server Cache for more information.

Build A Dropdown

Syntax is provided to build a dropdown list in an edit map. The dropdown may be built using data returned from a service script, a business service or a table.


Syntax	Description
uiHint:select="ss: "	Specify the name of the service script after the colon.
uiHint:select="bs: "	Specify the name of the business service after the colon.
uiHint:select="table: "	Specify the name of the table after the colon.

When specifying a service script or a business service, extra mapping information is needed to pass data to and from the service.


Syntax	Values	Description
uiHint:selectIn=" "	serviceXPath:element	Used to pass the value of another element into the service (mapping to the service's XPath).
uiHint:selectIn=" "	serviceXPath:'Literal'	Used to pass a constant or literal to the service (mapping to the service's XPath).
uiHint:selectOut="valuePath: ; descPath: "	See examples below.	Used to indicate which element in the service's output holds the values and which one holds the descriptions.

Examples:

<schema xmlns:uiHint="http://oracle.com/ouafUIHints">
    <boStatus mapField="BO_STATUS_CD" uiHint:select="bs:F1-BOStateReasonList" 
    uiHint:selectIn="boStatusBO:boStatusBO" uiHint:selectOut="valuePath:results/status; 
    descPath:results/description"/>
    ...
    <algorithm mdField="ALG_CD" uiHint:select="bs:F1-RetrieveSysEvtAlgorithms" 
     uiHint:selectIn="algorithmEntity:'F1AA';" uiHint:selectOut="valuePath:results/algorithm; 
     descPath:results/description"/>
    ...
    <outboundMsgType mdField="OUTMSG_TYPE_CD" required="true" fkRef="F1-OMTYP" uiHint:select="table:F1_OUTMSG_TYPE"/>
</schema>

Conditionally Hide Elements

The displayNone attribute is used to suppress elements on the map based on conditions.


Syntax	Values	Description
uiHint:displayNone=	"'XPath','value','!=' \| '='"	Used to conditionally hide this element based on the value of another element (referenced using its XPath). Enter a value of ' ' to interrogate a blank value. By default the operator is '='. This may be overridden using '!='.
uiHint:displayNone=	"function name, true \| false"	Used to indicate a JavaScript function, which must return a Boolean.

Warning:

Embedded spaces are not supported within the comma separated string values of this attribute.

This setting may be used on group nodes, list nodes, and elements - except for elements within a list. Elements within a list cannot be hidden conditionally.

The following example illustrates that two elements (currency reference and lookup) that will be hidden or displayed based on the value of the data type element. Note that this example also illustrates Trigger Dependent Behavior because the data type element's value may change and if it does, the condition for hiding the subsequent elements should be re-evaluated.

<schema xmlns:uiHint="http://oracle.com/ouafUIHints">
    ...
    <dataType mdField="F1_SE_DATA_TYPE" dataType="lookup" lookup="F1_SE_DATA_TYPE" 
     uiHint:dependents="currencyRef;lookup; "/>
     <currencyRef mdField="F1_SE_CURR_REF_LBL" uiHint:displayNone="'dataType','F1MO','!='"/>
     <lookup mdField="F1_SE_LOOKUP_LBL" fkRef="F1-LKUPF" uiHint:displayNone="'dataType','F1LP','!='"/>
     ...
</schema>

The following example illustrates referring to a function where the function receives parameters:

<uiHint:startSection mdField="F1_SE_DEFAULT_SECT" 
    uiHint:displayNone="isApplicableForSchemaType(item,'F1MP'),true"/>

Conditionally Protect Elements

The protect attribute is used to protect elements on the map based on other factors.


Syntax	Values	Description
uiHint:protect=	"'XPath','value','!=' \| '='"	Used to conditionally protect this element based on the value of another element (referenced using its XPath). Enter a value of ' ' to interrogate a blank value. By default the operator is '='. This may be overridden using '!='.
	"function name, true \| false"	Used to indicate a JavaScript function, which must return a Boolean.
	"'action','A' \| 'C','!=' \| '='"	Use the 'action' setting to protect the element based on the current action. For example, certain elements may only be specified when adding a record. Any subsequent changes to the record should protect the element from being changed. When using this option, the valid values for the 'value' are A (add) and C (change).

Warning:

Embedded spaces are not supported within the comma separated string values of this attribute.

The protect UI Hint may be used on group nodes, list nodes, and elements - except for elements within a list. Elements within a list cannot be protected conditionally.

The following UI Hint will protect the statistics category when the action is 'C'.

<schema xmlns:uiHint="http://oracle.com/ouafUIHints">
 ...
 <statisticsCategory dataType="lookup" mapField="STAT_CATEGORY_FLG" 
    lookup="STAT_CATEGORY_FLG" uiHint:protect="'action','C','='"/>
 ...
</schema>

Trigger Dependent Behavior

The dependents attribute is used to trigger behavior on a child element when a parent element is changed.


Syntax	Values
uiHint:dependents=" "	A list of one or more dependent elements separated by semicolons.

The following example illustrates that the dropdown list of one element is driven by the value of another element. In this example, when the Country changes, the list of States to choose from should change to only show the states for the indicated country.

<schema xmlns:uiHint="http://oracle.com/ouafUIHints">
  <country label="Country" uiHint:select="table:CI_COUNTRY" uiHint:dependents="state"/>
  <state label="State" uiHint:select="ss:CM-RetrieveCountryStates" 
   uiHint:selectIn="input/country:country;"  uiHint:selectOut="valuePath:output/state/stateCode; 
   descPath:output/state/stateDesc"/>
    ...
</schema>

Note:

Dependent targets may only name elements, not group or list nodes.

Do not modify the "id" attribute value of dependent and parent element. Data population in dependent is done based on the "id" attribute value.

Control Rendering Target

By default all elements that are not suppressed are visible on both the display map and the input map. Use the visibleOn attribute to limit the inclusion of an element to either the display or input map.


Syntax	Values
uiHint:visibleOn=	"displayMap"
uiHint:visibleOn=	"inputMap"

<schema xmlns:uiHint="http://oracle.com/ouafUIHints">
  ...
  <uiHint:includeMap map="StandardActionButtons" visibleOn="displayMap"
  ...
</schema>

Generate a Text Area

By default, a standard text box is rendered in an input map for any string element. If the field is larger and you wish to have a bigger text area (with a scroll bar), use the textArea attribute.


Syntax
uiHint:textArea="true"

<schema xmlns:uiHint="http://oracle.com/ouafUIHints">
   ...
  <message label="Message" uiHint:textArea="true"/>
  ...
</schema>

Modify FK Reference Defaults

By default, when an element with fkRef is displayed, an info string, context menu, navigation, and search are enabled (if the FK reference has been configured accordingly). Syntax is provided to allow you to selectively turn off any of these features.


Syntax
uiHint:fkRef="info:false;context:false;navigation:false;search:false;"

Only the feature that you wish to turn off needs to be specified. The following example illustrates turning off the navigation capability, meaning the text will not be rendered as hypertext.

<schema xmlns:uiHint="http://oracle.com/ouafUIHints">
   ...
   <attachmentID fkRef="F1-ATTCH" primeKey="true" suppress="input" uiHint:fkRef="navigation:false;"/>
   ...
</schema>

Fastpath: Refer to FK Reference Formatting in the UI Map Attributes section for more information on each FK reference setting.

Suppress Automatic Number Formatting

By default numeric fields (dataType="number") are formatted as numbers. An attribute is provided to instead apply alphanumeric formatting.

Note: If dataType is not specified explicitly, it is be derived from mdField or mapField.


Syntax
uiHint:alphaFormat="true\|false"

By default, its value is false (and therefore can be left out altogether).

Examples:

<schema xmlns:uiHint="http://oracle.com/ouafUIHints">
 ...
 <numberCount mdField="" dataType="number" uiHint:alphaFormat="true"/>
    ...
</schema>

Auto Capitalize the Input Data

The uiHint provides syntax to automatically capitalize input data.


Syntax
uiHint:capitalize="true\|false"

By default, its value is false (and therefore can be left out altogether).

<schema xmlns:uiHint="http://oracle.com/ouafUIHints">
 <toDoTypeCd mdField="TD_TYPE_CD" uiHint:capitalize='true' isPrimeKey="true"/> 
</schema>

Note: This attribute is ignored if uiHint:textArea="true" is configured.

The attribute is only available in the schema designer when the isPrimeKey is set to true. The attribute may be added to any string element when using the source viewer.

Override Row Header for Accessibility Purposes

When generating the HTML for a list, the default is to assign scope="row" to the non-suppressed primary key elements, if any, or the first non-suppressed element in the list. This uiHint provides syntax to override the defaults when they are not the appropriate elements to be used by a screen reader.


Syntax
uiHint:rowHeader="true\|false"

<iwsAnnotationTypeParameter mdField="F1_ANN_TYPE_PARMS_LBL" type="list" mapChild="F1_IWS_ANN_TYPE_PARM">
        <sequence dataType="number" mapField="SEQ_NUM" uiHint:rowHeader="false"/>
        <parameterName mapField="PARM_NAME" uiHint:rowHeader="true" dataType="string"/>
        <parameterValue mapField="PARM_VALUE" dataType="string"/>
        <isRequired dataType="lookupBO" mapField="REQUIRED_SW" lookupBO="F1-BooleanValues"/>
        <javaPackage mapField="JAVA_PACKAGE" dataType="string"/>
        <version suppress="true" dataType="number" mapField="VERSION"/>
        <description mapField="DESCR" dataType="string"/>
        <longDescription mapField="DESCRLONG" uiHint:textArea="true" dataType="string"/>
        <owner suppress="input" dataType="lookup" mapField="OWNER_FLG" lookup="OWNER_FLG"/>
    </iwsAnnotationTypeParameter>

The attribute is only applicable to elements in a list.