Input/Output Text Usage Guideline

RCUX Document Version 5.2.0 for Oracle® Fusion Middleware 11g Release 1 Patch Set 1 (11.1.1.2.0)
Last Updated 23-Feb-2011

The Input/Output Text component is used to enter plain text. The Text Field is used for a single-line text entry. The Text Area is used for multiple-line text entry.

Guideline Contents

• General Principles
• Elements
• Prompt
• Text Box
• Value
• Contextual Info
• Required Field Indicator
• Changed Field Indicator
• Help Text
• Auto-Suggest in Text Fields
• Manual Truncation

Related Guidelines

Guideline	Section	For Information About
Slider	All	Alternative to Input/Output Text box for numeric values within a fixed range.
Spinbox	All	Alternative to Input/Output Text box for numeric values with fixed increments.
Help Framework	Help note windows	Help method used with Input/Output Text.
Message Framework	All	Message methods used with Input/Output Text.
Form Layout	All	Commonly used to organize Input/Output Text boxes.
Headers	Truncation	Resize truncation of long values in any resizable container.

Related ADF Elements

Refer to the ADF Faces Rich Client demos page to find demos and tag documentation for the ADF elements related to this component:

ADF Element	Notes
af:inputText	Component supporting plain text; supports typed text input and display.
af:outputText	Component supporting plain text; text display only.
af:outputFormatted	Component supporting styled text; text display only.
af:contextInfo	Adds a contextual info component.
af:insertTextBehavior	Allows a command component to insert text into an input component.
af:autoSuggestBehavior	Shows a list of suggested values that match a partial string in input text.

General Principles

Purpose:

To enter one or more lines of plain text.

  

Default Text Field and Text Field in a Global Layer

 

Input/Output Text Area

Usage:

• An Input/Output Text Box may be used within a table cell or form layout. A text box may also be used as a stand-alone component.
• There are two types of Input/Output text boxes: Text Field and Text Area.
• A text field is used to enter or display a single line of text.
• A text area is used to enter or display multiple lines of text.
• If numeric input may have fixed ranges or increments, consider using a Spinbox or Slider instead.

Elements

See the images in General Principles for the elements of a text field and text area.

Prompt

Purpose:

Identifies the purpose of the text box.

Usage:

• Use of prompts is strongly recommended in a form layout. In a table layout, the column header is the prompt.
• There is no limit to the number of characters allowed in the prompt, but product teams must make sure that the layout allows for prompts to become up to 100 percent longer in translation.
• Prompts may be placed before or above a text box. Place the prompt before the text box in most cases. If horizontal space is an issue, such as inside an accordion pane, place the prompt above the text box.
• Prompts may be visually omitted when the function of the text box is obvious to the product's users without displaying a label, typically because the preceding header helps identify the field.
• When a prompt is visually omitted, provide a hidden prompt label so that accessibility tools, such as screen readers, can still read a prompt for the data.
• Prompts should use headline capitalization. See Capitalization in the Language in UI guideline for details.

Text Box

Purpose:

Displays text or blank values.

Description:

• If the width of the Input/Output text box is shorter than the length of the value:
• Text Field: The value is clipped.
• Text Area: Text wraps to the next line or horizontally scrolls.
• If a text area is not large enough to display all of its contents, a vertical scroll bar appears.

Usage:

• The recommended default width of the box is 30 characters (EMs) or 170 pixels; however, the width of the box can be set by product teams. The recommended default height for a text area is three lines.
• Product teams can increase or decrease the size of a text box according to expected content.
• It is recommended to allow text to wrap in a text box. Wrapping should be turned off only when the text box is expected to contain many long strings without spaces, such as URLs or e-mail addresses.
• The box should be disabled when users are not able to enter data, but it is still necessary to display the box because it may be enabled in different contexts.
• The box should be shown as read-only when data is displayed in a read-only page, such as a printable page. Read-only data may also be displayed when the user has permission to view the text, but not to edit it.
• When using a text area to display read-only content with hard line breaks, such as a contract, set the box width to avoid additional line breaks that make the content harder to scan. When the box is read only, the box does not render; only the value within the box renders as plain text.
• Product teams should size text boxes to fit the data the user is likely to enter. This provides a visual cue for the amount of input expected, and makes it easier to review the text in the field by avoiding data clipping and minimizing scrolling. For example, a box expecting a US postal code might be 10 characters (EMs) or 60 pixels wide, and a box expecting a US area code might be five characters (EMs) or 28 pixels wide.

Read-Only Text Area with Scroll Bar

Value

Purpose:

Displays data within the Input/Output text box.

Usage:

• If a default or pre-existing value exists, it should be displayed in the text box regardless of its state. Otherwise, the text box should be displayed without a value. For example, if a user wants to change an address, the previous address would be displayed, but when the user enters an address for the first time, the fields would be blank.
• A text field may include a numeric value that is used to perform automatic calculations, such as totals. A text area may also include numeric values, but the values should not be used to perform automated calculations.

Contextual Info

Input/Output Text can accommodate a contextual information pop-up dialog to offer more information or related actions for an item in the text field or text area. See the contextInfo guideline for information.

Required Field Indicator

Purpose:

Identifies fields that must be completed before submitting the page.

Description:

• The Required Field Indicator is a text asterisk, *.
• The Required Field Indicator does not render if a text box is disabled or read-only.

Example:

When creating a new service request, contact information may be required for follow-up. In this case, product teams can make some of the contact information text boxes required, such as "Name" and "Address."

Usage:

ADF provides ALT text and tooltips to indicate required fields. Product teams may additionally provide key notation to define the Required Field Indicator. Refer to Key Notation in the Headers guideline for information regarding usage.

Changed Field Indicator

Purpose:

Indicates that the value in the Input/Output text box changed after page submission.

Usage:

• The Changed Field Indicator should persist until the page is refreshed. If a scenario requires the indicator to persist after page refresh, the Changed Field Indicator may remain displayed as long as needed. For example, when changing an employee's name after marriage, the "Name" field might display a Changed Field Indicator once the final revision is submitted.
• ADF provides ALT text and tooltips to indicate changed fields. Product teams may additionally provide key notation to define the Changed Field Indicator. Refer to Key Notation in the Headers guideline for information regarding usage.

Help Text

Purpose:

Provides users with additional information about the text box.

Usage:

Help text should be provided when users may be unclear about the type of data to be entered. See the Help Framework guideline for details.

Auto-Suggest in Text Fields

Purpose:

Auto-Suggest presents a filtered list of search results in a text field when a user begins typing an entry.

Usage:

• Most regular text fields do not need Auto-Suggest. Use Auto-Suggest only when a text field value can come from a pre-determined set of 10 or fewer values, and includes the option for the user to enter a custom value.
• If there are only pre-determined values, use a choice list.
• If there are only custom values, use a text field without Auto-Suggest.
• Auto-Suggest can be useful in text fields in situations such as a search engine, where a potentially infinite number of possible matches leaves no choice but to present the top 10 most popular keywords for a partial string.

Manual Truncation

Product teams may manually truncate strings in rare cases where space may be limited (such as the content region of a panelBox).

Purpose:

Shortens strings to fit within their container or region.

Description:

• Only read-only text strings (Output Text) may be truncated. Truncation occurs only at the end of a string.
• When a string is truncated, it shows an ellipsis (. . .) in place of the missing characters. The full string appears in a tooltip on hover.
• Text strings are truncated before rendering, regardless of how much space is available.
• Truncation is character-based and is applicable to all languages regardless of character set, including languages with ideographic characters, such as Chinese. All characters, including spaces and symbols—such as underscores ("_"), periods ( "."), and so on—are counted.
• In right-to-left languages, such as Arabic, truncation also occurs from right-to-left, and the ellipsis is placed to the left of the truncated string. The truncation direction depends on the language and script in which the string is rendered, not on other factors, such as the user's language preference or the direction of the page layout.
• Truncation is disabled in Oracle Accessibility Mode.

Truncated Strings in Table Cells

Usage:

• Manual truncation may be used when a component does not automatically provide truncation, or when product teams wish to customize the positioning of truncated text.
• Truncation reduces readability. Where possible, applications should provide enough space for the full display of strings, and minimize use of truncation.
• Strings may not be truncated to less than the minimum number of characters allowed, which is 15 characters, including three characters for the ellipsis.
• Manual truncation may cause problems when strings are translated, because strings may become longer or shorter. Consequently, manual truncation should be used only when automatic truncation is not appropriate. For example, when the truncated text is a summary or introduction to a full details page with other content, it is more appropriate to truncate the text manually rather than relying on automatic truncation.

Examples:

String Type	Full String	Truncation
File Name	customization_template.psd	customizatio…
Meeting Name	Robert's Weekly Budget Update	Robert's Wee…
Customer Name	Larry's Plumbing and Supplies	Larry's Plum…
Expense Report Name	DIS2002 Conference Trip	DIS2002 Conf…

• It is recommended to provide another method to display the full name of the object or attribute. The method used depends on the length of the string:
• Display strings consisting of a single, brief paragraph in a tooltip. For example, the full text of a truncated object name can be displayed in a tooltip without obscuring too much of the page.
• Use a drill-down link or other navigation method to display verbose strings or strings consisting of multiple paragraphs. For example, when the truncated text is a summary or introduction to a full details page with other content, it would be impractical to read the content in a tooltip, so a drill-down link would be a better solution.

• The ellipsis used for truncation consists of three periods with no intervening spaces—a total of three characters. It is neither the "&hellip" character entity reference (…), commonly used in Web pages, nor is it a combination of periods combined with non-breaking spaces (as in Oracle documentation).
• Product teams can provide a custom tooltip for a text-based component; however, if the text is truncated, the full string of text is appended to the custom tooltip text.

Truncation vs. Clipping

Clipping is browser-based behavior that occurs when some elements become occluded by other elements because there is not enough horizontal or vertical space to show all elements simultaneously. Typically, horizontal or vertical scrollbars appear in the region that is subject to clipping.

Clipping is not truncation—there is no ellipsis, no minimum length, and no tooltip to show the complete string.

Window Resize Resulting in Clipping