UI Map Standards
Contents
Basic UI Map Templates
All UI Maps share the same basic structure regardless of placement (page area, zone, pop-up) or usage (display only, input).
Sample XML
All information in this document is based upon the following XML structure.
Display Only UI Map
<html>
<head>
<title oraMdLabel="ADDRESS_LBL"></title>
<link rel="stylesheet" type="text/css" href="cisDisabled.css"/>
<link rel="stylesheet" type="text/css" href="cisEnabled.css"/>
</head>
<body class="oraZoneMap">
<table cellspacing="4" width="100%">
<colgroup>
<col class="oraLabel oraTableLabel" />
<col class="oraNormal oraTableData" />
</colgroup>
<tr>
<td oraLabel="address"></td>
<td oraField="address"></td>
</tr>
<tr>
<td oraLabel="city"></td>
<td oraField="city"></td>
</tr>
<tr>
<td oraLabel="state"></td>
<td oraField="state"></td>
</tr>
<tr>
<td class="oraSectionEnd" oraLabel="zip"></td>
<td class="oraSectionEnd" oraField="zip"></td>
</tr>
<tr>
<td colspan="2" class="oraSectionHeader" oraMdLabel="CONTACT_LBL"></td>
</tr>
<tr>
<td colspan="2" class="oraSectionStart oraEmbeddedTable">
<table oraList="contactInformation" cellspacing="2">
<thead >
<tr>
<th class="oraGridColumnHeader" nowrap="nowrap">
<span oraLabel="contactInformation/type></span>
</th>
<th class="oraGridColumnHeader" nowrap="nowrap">
<span oraLabel="contactInformation/number"></span>
</th>
</tr>
</thead >
<tbody>
<tr>
<td class="oraNormalAlt oraDisplayCell">
<span oraField="type"></span>
</td>
<td class="oraNormal oraDisplayCell">
<span oraField="number"></span>
</td>
</tr>
</tbody>
</table>
</td>
</tr>
</table>
</body>
<xml>
<root>
<address>123 Main St</address>
<city>Alameda</city>
<state>CA</state>
<zip>94770</zip>
<contactInformation>
<type>Home Phone</type>
<number>510-555-2287</number>
</contactInformation>
<contactInformation>
<type>Cell Phone</type>
<number>510-555-4285</number>
</contactInformation>
</root>
</xml>
</html>
Input UI Map
<html>
<head>
<title oraMdLabel="ADDRESS_LBL"></title>
<link rel="stylesheet" type="text/css" href="cisDisabled.css"/>
<link rel="stylesheet" type="text/css" href="cisEnabled.css"/>
</head>
<body>
<table width="100%" cellpadding="12">
<tr class="oraErrorText">
<td><a href="" onclick="oraShowErrorAlert(); return false;">
<span class="oraErrorText" oraErrorVar="ERRMSG-TEXT"></span></a>
</td>
</tr>
</table>
<table cellspacing="4" width="100%">
<colgroup>
<col class="oraLabel oraTableLabel" />
<col class="oraNormal oraTableData" />
</colgroup>
<tr>
<td oraLabel="address"></td>
<td><input type="text" oraField="address"/></td>
</tr>
<tr>
<td oraLabel="city"></td>
<td><input type="text" oraField="city"/></td>
</tr>
<tr>
<td oraLabel="state"></td>
<td><input type="text" oraField="state"/></td>
</tr>
<tr>
<td oraLabel="zip"></td>
<td><input type="text" oraField="zip"/></td>
</tr>
<tr>
<td colspan="2" class="oraSectionHeader" oraMdLabel="CONTACT_LBL"></td>
</tr>
<tr>
<td colspan="2" class="oraSectionStart oraEmbeddedTable">
<table oraList="contactInformation" cellspacing="2">
<thead >
<tr>
<th class="oraGridColumnHeaderButton"></th>
<th class="oraGridColumnHeaderButton"></th>
<th class="oraGridColumnHeader" nowrap="nowrap">
<span oraLabel="contactInformation/type></span>
</th>
<th class="oraGridColumnHeader" nowrap="nowrap">
<span oraLabel="contactInformation/number"></span>
</th>
</tr>
</thead >
<tbody>
<tr>
<td oraType="addGridRow"></td>
<td oraType="deleteGridRow"></td>
<td>
<input type="text" oraField="type"/>
</td>
<td>
<input type="text" oraField="number"/>
</td>
</tr>
</tbody>
</table>
</td>
</tr>
<tr>
<td colspan="2" class="oraSectionStart oraEmbeddedTable">
<table cellspacing="2">
<tr>
<td>
<input class="oraButton" oraMdLabel="C1_SAVE_LBL" type="button"
onClick="oraSubmitMap('OK');"/>
</td>
<td>
<input class="oraButton" oraMdLabel="CANCEL_LBL" type="button"
onClick="oraSubmitMap('CANCEL',false);"/>
</td>
</tr>
</table>
</td>
</tr>
</table>
</body>
<xml>
<root>
<address>123 Main St</address>
<city>Alameda</city>
<state>CA</state>
<zip>94770</zip>
<contactInformation>
<type>Home Phone</type>
<number>510-555-2287</number>
</contactInformation>
<contactInformation>
<type>Cell Phone</type>
<number>510-555-4285</number>
</contactInformation>
</root>
</xml>
</html>
Basic HTML and Styles
The basic templates introduced the standard HTML and styles used for UI Maps. These standards are described individually in the following sections.
Stylesheets
The styles to apply the standard look to the maps are all contained in stylesheets. These stylesheets should be included in all UI Maps.
...
<link rel="stylesheet" type="text/css" href="cisDisabled.css"/>
<link rel="stylesheet" type="text/css" href="cisEnabled.css"/>
...
Title
Each UI Map should have a <title> tag.
...
<title oraMdLabel="ADDRESS_LBL"></title>
...
This will give the UI Map a descriptive title.
• If the UI Map is presented in a "pop-up", the title will be in the window title bar.
• If the UI Map is presented in the page area, the title will be added as a <span> tag to the UI Map and will appear at the top of the UI Map.
• If the UI Map is presented as a zone map, it will be ignored. The <title> tag should still be included in the HTML as standard.
Zone Maps
When the map is presented in a zone as part of a portal, the UI Map should have a border so that the information is "contained" within the zone.
...
<body class="oraZoneMap">
...
Page Area Maps vs Pop-Up Maps
The presentation of the UI Maps can vary from design to design. The following standards have been applied to decide when to use a Page Area UI Map and when to use a Pop-Up Map:
• If there are multiple UI Maps in the sequence, always use the Page Area.
• If the UI Map has many input fields, always use a Page Area.
• If the UI Map is a "confirmation" type dialog or only has one or two input fields, use a Pop-Up.
Note:
The difference between "just a few input fields" and "many input fields" can be discretionary. The final decision should rest with the dialog designer.
Error Messages
Input maps have a ability to present error messages to the User.
This HTML structure provides the provides the necessary elements and functions to display errors to the User. It should be directly after the <body> tag. When there is no error, nothing will be visible on the UI Map. It will be made visible if an error occurs and the UI Map is re-presented to the User. Clicking on the link (when visible) will result in a pop-up alert appearing with the long error message text.
Standard Layout and Styles
The information is presented on the UI Map by using a <table> to organize the information in rows and columns.
The <colgroup> and <col> tags allow for the application of classes to the columns (the label is in the first column and the data is in the second column.). Using these tags mean that the class attribute (to apply styles) does not need to be defined on every <td>.
Grids (Tables of Data)
A UI Map could contain information that is best presented as a grid. These are referred to as "Embedded Tables". The embedded table can be used to display information or input information.
Example Embedded Table HTML
The embedded table will be included within a row (<tr>) of the basic layout:
Embedding the Table
The embedded table is included within the overall table structure. The colspan attribute ensures that the embedded table can span the standard two columns of the overall layout table.
...
<tr>
<td colspan="2" class="oraEmbeddedTable">
...
...
...
</td>
</tr>
...
Embedded Table Structure
The embedded table is very similar to the basic layout table.
• The <table> tag has a slightly smaller cellspacing and it defines the "list" element contained in the XML that will be used to provide the data.
• The <thead> element is used to give the embedded table headings for the columns.
• The <tbody> element is the element that will be repeated for each referenced "list" element in the XML. In the previous example, there are two "contactInformation" list elements, so the displayed embedded table will have two rows.
Column Headings
Embedded tables should have headings for the displayed columns. The <thead> tag defines these.
...
<thead>
<tr>
<th class="oraGridColumnHeader" nowrap="nowrap">
<span oraLabel="contactInformation/type></span>
</th>
<th class="oraGridColumnHeader" nowrap="nowrap">
<span oraLabel="contactInformation/number"></span>
</th>
</tr>
</thead>
...
The "nowrap" attribute prevent the column heading from taking multiples lines. If multiples lines are required, the "nowrap" may be removed.
Input Fields
Embedded tables may be used for input as well as display only. The framework provides a convenient control to assist in the creation of editable embedded tables.
There are two new columns added to the input embedded table.
• oraType="addGridRow" will add a "+" button to the row. This will allow the User to add an additional row to the existing grid.
• oraType="deleteGridRow" will add a "-" button to the row. This will allow the User to delete an existing row from the grid.
Note:
The <thead> tag also requires these two new columns to be added.
These controls are, as standard, placed at the beginning of the row in the order shown. Either of the controls may be omitted if required (if, for example, Users are not permitted to delete information).
The presence of either of these controls will activate the "empty list" process. This means that if the XML has no data for the "list" specified, the input grid will display with an empty row ready for the input of new information.
Action Buttons
Example Action Button HTML
Action buttons are used to perform some specified function from the UI Map. The actions are as varied as the information being displayed/updated. Below are two common examples:
• Save. Normally used on an Input UI Map to allow a User to save any changes they have made.
• Cancel. Normally used on an Input UI Map to allow a User to cancel changes in progress.
Button Standards
The following points highlight some standards related to buttons.
• Buttons are included as an embedded table.
• Buttons should be grouped together. They should not be placed in different areas of the UI Map.
• The location of the buttons depends mainly on the type of UI Map.
◦ Display Only UI Maps should have a Record Actions section in the upper right section of the UI map.
◦ Input UI Maps should have the buttons at the foot of the UI Map (after all input fields).
Available Styles
Styles are all contained in the referenced CSS stylesheets. They are applied by the HTML "class" attribute. The actual style settings used are not documented here as they may be adjusted. This section only specifies when a particular style should be used.
Note:
The "class" attribute may reference more than one style (class="oraLabel oraSectionEnd")
Style | Comments | Example |
|---|
oraButton | Applied to <input> elements where the type is button. | ...
<input class="oraButton"
oraMdLabel="CANCEL_LBL"
type="button"
onClick="oraSubmitMap('CANCEL',false);"/>
... |
oraDisplayCell | Applied to the <td> tag of an embedded table. It defines how the table cell looks (not the data contained inside the cell). | ...
<td class="oraDisplayCell">
<span oraField="type"></span>
</td>
... |
oraEmbeddedTable | Applied to the <td> tag that will contain the embedded table. | |
oraError | This style is applied to elements that are identified as "error elements". Refer to Display Errors for more information. Note:
This style is not normally applied directly in the UI Map HTML | |
oraErrorText | This style is applied to the elements concerned with error messages. | |
oraGridColumnHeader | This style is applied to the <td> tags that define column headers within embedded table. | ...
<thead >
<tr>
<th class="oraGridColumnHeaderButton"></th>
<th class="oraGridColumnHeaderButton"></th>
<th class="oraGridColumnHeader"
nowrap="nowrap">
<span oraLabel="contactInformation/type>
</span></th>
<th class="oraGridColumnHeader"
nowrap="nowrap">
<span oraLabel="contactInformation/number">
</span></th>
</tr>
</thead >
... |
oraGridColumnHeaderButton | This style is applied to the <td> tags that define the column headers for the "+" and "-" buttons used on editable embedded tables. | ...
<thead >
<tr>
<th class="oraGridColumnHeaderButton">
</th>
<th class="oraGridColumnHeaderButton">
</th>
<th class="oraGridColumnHeader" nowrap="nowrap">
<span oraLabel="contactInformation/type>
</span></th>
<th class="oraGridColumnHeader"
nowrap="nowrap">
<span oraLabel="contactInformation/number">
</span></th>
</tr>
</thead >
... |
oraInput | This style is applied to input fields: • <input type="text"> • <input type="checkbox"> • <select> • <textarea> Note:
This can normally be omitted as input styles are applied automatically when oraSchemaDataTypes="true". | ...
<input type="text" class="oraInput"
oraField="address"/>
... |
oraInputMoney | This style is applied to input fields: • <input type="text"> • <select> (rare) • <textarea> (not recommended) Note:
This can normally be omitted as input styles are applied automatically when oraSchemaDataTypes="true". | ...
<input type="text" class="oraInputMoney"
oraField="amount"/>
... |
oraInputNumber | This style is applied to input fields: • <input type="text"> • <select> (rare) • <textarea> (not recommended) Note:
This can normally be omitted as input styles are applied automatically when oraSchemaDataTypes="true". | ...
<input type="text" class="oraInputNumber"
oraField="count"/>
... |
oraLabel | This style is applied to standard label fields that are right aligned. Note:
This can normally be omitted as it is applied by the <col> tag. | ...
<td class="oraLabel"
oraLabel="address"></td>
... |
oraLabelAlt | This style is applied to standard label fields only if it is desired to have the label aligned to the left. | ...
<td class="oraLabelAlt"
oraLabel="address"></td>
... |
oraLabelCenter | This style is applied to standard label fields only if it is desired to have the label aligned in the center of the cell. | ...
<td class="oraLabelCenter"
oraLabel="address"></td>
... |
oraLink | This style is applied to foreign key references (links). This is automatically added by the UI Map framework but can also be used manually if desired. | |
oraNormal | This style is applied to standard data fields (display only) that are left aligned. Note:
This can normally be omitted as it is applied by the <col> tag. | ...
<td class="oraNormal"
oraField="address"></td>
... |
oraNormalAlt | This style is applied to standard data fields (display only) only if it is desired to have the data aligned to the right. | ...
<td class=" oraNormalAlt"
oraField="address"></td>
... |
oraNormalCenter | This style is applied to standard data fields (display only) only if it is desired to have the data aligned in the center of the cell. | ...
<td class=" oraNormalCenter"
oraField="address"></td>
... |
oraPageTitle | This style is applied to the element that contains the page title. Note:
This style is not normally applied directly in the UI Map HTML. The <span> is created by the UI Map framework when the UI Map is displayed in the page area. | ...
<span class=" oraPageTitle"
oraMdField="PAGE_TITLE_LBL"></span>
... |
oraSectionEnd | This style is applied to the <td> tags at the end of a "section" (group of elements). It provides some space to separate the section from the following information. Note:
The style must be applied to both <td> tags or the label may be misaligned with the data/input. | ...
<tr>
<td class="oraSectionEnd"
oraLabel="zip">
</td>
<td class="oraSectionEnd"
oraField="zip">
</td>
</tr>
... |
oraSectionHeader | This style is applied to the <td> tag used to give a heading for a section within the information being displayed. It does not provide spacing before or after itself. The oraSectionStart and oraSectionEnd classes are used for this. Note:
The section header should span both the label column and the data column. | ...
<tr>
<td class="oraSectionHeader"
colspan="2"
oraMdField="DATA_SECTION_LBL"></td>
</tr>
... |
oraSectionStart | This style is applied to the <td> tags at the start of a "section" (group of elements). It provides some space to separate the section from the previous information (often a section header). Note:
The style must be applied to both <td> tags or the label may be misaligned with the data/input. | ...
<tr>
<td class="oraSectionStart"
oraLabel="zip"></td>
<td class="oraSectionStart"
oraField="zip"></td>
</tr>
... |
oraTableData | This style is applied to the <col> tag for the data column of the main table (second column). It is used to provide a percentage width for the horizontal space to be used for the information. | ...
<colgroup>
<col class="oraLabel
oraTableLabel"/>
<col class="oraNormal
oraTableData"/>
</colgroup>
... |
oraTableLabel | This style is applied to the <col> tag for the label column of the main table (first column). It is used to provide a percentage width for the horizontal space to be used for the labels. | ...
<colgroup>
<col class="oraLabel
oraTableLabel" />
<col class="oraNormal oraTableData"/>
</colgroup>
... |
oraTinyText | This style is typically applied directly beneath an <input> tag to provide information or a hint to the user concerning information relevant to the input. For example, name or address format. | |
oraZoneMap | This style is used applied when the UI Map is to be displayed as a zone on a portal. | ...
<body class="oraZoneMap">
... |
Using OJET
There are some UI maps delivered by the product that use UI widgets provided by Oracle JavaScript Extension Toolkit (OJET). Releases for OJET do not always align with releases of the framework. In addition, there are times when OJET adjusts APIs that the product uses. The framework will attempt to ensure that each release of the product has the latest and greatest version of the OJET libraries. Implementations are discouraged from attempting to use features in OJET that are not used by the product because the product is not necessarily testing those features and is not ensuring that upgrades to the APIs for those features are backward compatible.
Note that the product isolates the references to OJET into a UI map fragment that is included in the maps that use OJET widgets. This is so that changes to future versions of OJET are minimized to a single place. The map is called F1–OJETLIBS. If your implementation wants to use OJET, the recommendation is to use this UI map fragment.
Parent topic