Input/Output Text Usage Guideline Bookmark this Guideline Printable Page


RCUI 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

Note: Images in this guideline are provided as a general reference, and may not be exact representations of FusionFX pages.

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 Bookmark this Heading Return to Top

Purpose:

To enter one or more lines of plain text.

Default Input Text Field   Input Text Field in Global Layer, featuring a Required Field Indicator, the input text prompt and the input text area. </p>

Default Text Field and Text Field in a Global Layer

 

Elements of the Text Area: featuring a Required Field Indicator, Changed Field Indicator, text area prompt and the input text area.

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.
Note: Input/Output Text boxes are implemented using the af:inputText component. If the number of rows is set to one, the result is a text field; if the number of rows is set to two or more, the result is a text area.

Elements Bookmark this Heading Return to Top

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

Prompt Bookmark this Heading Return to Top

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 Bookmark this Heading Return to Top

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.

A read-only Text Area featuring the prompt to the left of the text area, and a scroll bar on the right side of the text area.

Read-Only Text Area with Scroll Bar

Value Bookmark this Heading Return to Top

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 Bookmark this Heading Return to Top

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 Bookmark this Heading Return to Top

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 Bookmark this Heading Return to Top

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 Bookmark this Heading Return to Top

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 Bookmark this Heading Return to Top

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 Bookmark this Heading Return to Top

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

Note: Resize truncation is provided by ADF to automatically resize strings in components with resizable fields. See the Truncation section in the Headers guideline for more information.

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.

A table in which the text string in cell is truncated, so that ellipses are displayed to indicate truncation.

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.

Note: In addition to tooltips, some product teams may use note windows on a component. In this case, both note windows and tooltips are displayed together. See the Secondary Windows guideline for details.

Truncation vs. Clipping Bookmark this Heading Return to Top

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.

An example of a browser window in three different sizes, showing the resultant clipping that occurs automatically on resize.

Window Resize Resulting in Clipping