Contextual Actions Guidelines Print this Page

Contextual actions provide related information and actions to users within the immediate context of the object instances upon which they act.


Intended Audience for This Document
Return to Top

All stakeholders involved in designing and implementing contextual actions should review this document. These stakeholders include providers and consumers.

Providers are those teams who provide contextual action dialogs for an object or objects which they own. Consumers are those teams who will enable the provided contextual actions dialogs within their applications on the appropriate objects.  Example: The Trading Community team provided the contextual actions dialog for external person and organization, but various CRM, FIN and HCM teams will enable it for use in their applications. In this case Trading Community is the Provider and all the other teams are the Consumers.

This document is aimed primarily at Providers, because they are the ones involved in designing Contextual Actions dialogs.

General Principles
Return to Top

Description and Purpose

Contextual actions quickly and easily bring related information and actions to users within the context of the object instance upon which they act. At the same time, because these contextual actions are available only when invoked by users and appear temporarily on top of the existing page, they don’t take up valuable screen real estate.

Contextual actions:

  • Minimize disruption to users by making information and actions immediately available to them when and where they are needed.
  • Reduce the need for users to navigate between work areas. Users can enter or view more information without leaving the current page context.
  • Reduce the need for users to load a new page or to refresh a page and then link back to the original context.
  • Provide quick access to other parts of the current work area or other work areas if needed.
  • Provide quick access to tools that support collaboration with a selected person (in the case of internal and external person objects).
  • Enable provider teams to easily offer encapsulated data, business logic, and messaging.
  • Enable consumer teams to provide ad hoc information and tasks, without overloading the current work area and without recoding.

Example of a Contextual Action

The following example illustrates a users’s interaction with the contextual action (i-pop) affordance and a contextual action dialog. While there are seemingly several steps involved in interacting with the contextual action dialog, these steps are seamlessly connected to make the entire interaction seem like a single, fluid action.

Figure 1. When you access a page, the contextual action glyph is visible on any field that is contextual action-enabled. When you move your cursor into a cell that has a contextual action available in it, no interaction with the contextual action is invoked.
Figure 2. When you move your cursor near the glyph, that glyph enlarges and displays an icon, called an "i-pop" to indicate that more information is available.
Figure 3. When you click the i-pop, a contextual action dialog that contains additional detail appears over a limited portion of the current page.
Note: The visual representations and interactions described in this document are proposed designs; they are subject to change based on development commitment.
Provider Guidelines
Return to Top

When designing contextual actions dialogs, the provider teams should keep the following guidelines in mind:

  • The actions and information within the contextual action dialog should be grouped according to usage. (See the Layout section in this document.)
  • Navigation from the dialog occurs in the same way that you would navigate from a link on the page; if any unsaved changes exist, a warning dialog appears.
  • Ensure that launching, nesting, moving, and navigating from the dialog complies with all existing dialog guidelines. (See secondary windows guidelines for more information.)
  • The actions within the contextual action dialog may:
    • take you to a different point in the current work area.
    • take you to a different work area.
    • open another dialog.
    • open another browser window.

When designing interactions that navigate the user outside the current work area, no return navigation is provided, unless the new work area is launched in a separate window which can be closed.

When launching contextual actions from dialogs or dialogs from contextual actions, close the first dialog, unless you have a need for the first to remain open. For example, when the user expects to continue looking at or working with the first dialog after dismissing the second, or when doing comparisons between the two.

Contextual Actions dialogs should be modeless, rather than modal. This allows the user to work with the underlying page.

Consumer Guidelines
Return to Top

Contextual actions providers provide the regions inside the Contextual Actions dialogs, but the dialogs themselves are not provided as part of the contextual actions framework.  This means that the Dialog titles and button need to be specified by the consuming teams.

Dialog Titles

Dialog Titles need to be specified by the consuming application in order to include the specific object type name for the current context. The title should be the most specific that the consuming team can provide.  This will usually be the label for the field or table column in which the contextual action is enabled:

Follow this format for the title bar of the dialog:
[specific object type]: [object instance name]

This format for the title bar is followed for all contextual action dialogs except for the Person contextual action. In case of a Person contextual action, the title displays only the name of the person, i.e. the name on which the contextual action was initiated [object instance name].

Figure 4. Example dialog using title bar formatting guideline


  • Person
    Territory Owner: Bill Haskins
  • Organization
    Opportunity:  XYZ Corporation
  • Date
    Received Date: 01/03/09
  • Currency
    Accounted Currency: 1,2093 USD
  • Time
    Time Entered: 10:30am CST

Use Done not OK

Consumers need to ensure they use Done, not OK to close the Contextual Action dialogs since the dialog is read-only. (See the page actions guidelines for more information)

Multi-Field Addresses

When an address is parsed into several fields, enable the glyph on the Address Line 1 field.  The glyph on Address Line 1 field should be understandable from the user’s perspective since Address Line 1 is the most specific part of the address and the title of the Contextual Actions Address dialog that one would see first.

Although the glyph only appears on Address Line 1, the entire address context needs to be passed to the Contextual Actions address pop-up.

Showing Glyphs in Dialogs

In general, dialogs are a quick step en route to a primary task and should be kept as simple as possible. As a result it is not always clear whether or not it is necessary to show glyphs for objects which may appear in such dialogs (e.g. addresses returned with a list of names in a select and add dialog).

If contextual information about these objects could plausibly help users complete the main task of the dialog (e.g. pick the correct person from a list), the glyphs should be shown. If the contextual information is unlikely ever to be used to complete the task of the dialog, the glyphs may be omitted.

Glyph Appearance

Figure 5. No glyph should appear in an editable field until data has been entered in the field and focus has been moved to another field. If a field previously holding a value with a glyph is cleared by the user, the glyph should also be removed.

Validation will occur upon change focus; the round-trip to server is considered acceptable, so it is not necessary to wait until clicking the i-pop to validate. This way determining whether to display the glyph and the ability to display the dialog are consolidated into one validation.

If the field is not empty at the start, then the glyph shows. But if the user clears any part of the content or starts typing in the field, the glyph disappears and does not appear again till the information is committed. After committing, the glyph will show and the Contextual Actions will show the newly committed information.

Return to Top

This section describes the controls and functionality that are available to support the design team’s need for extensibility in contextual actions. Note that currently the provider is responsible for creating the entire dialog. If consumers have extensibility needs, they must submit their requirements to the provider.


Contextual actions will be available on any controls that can render data, including but not limited to the following:

Figure 6. Table cells*
Figure 7. Read-only fields
Figure 8. Drop-down lists and LOV Choice fields
Figure 9. Page headers
Figure 10. Editable fields**
Figure 11. Links

Note: If you have a table cell which has an editable field in it, only enable contextual actions on the editable field, rather than both on the cell level and the editable field.

**Note on editable fields: No glyph should be displayed until data is entered into the field. Once the first character is entered, a glyph is visible.

Basic Layout of a Contextual Action Dialog

Providing teams should consult with their UX points of contact (POCs) for a design that best suits their needs.

Figure 12. Use this example and Figure 13. as a guide when designing the basic layout of a contextual action dialog.
Figure 13. Example contextual action dialog layout

Tabs in Contextual Actions

No tabs are currently supported in Contextual Actions.

Image Sizing

To avoid obscuring the underlying page, keep the Contextual Actions dialog as small as possible, no more than 100 x 130 pixels. Ensure that any imported images are scaled to maintain their aspect ratio.

Sizeable Information Blocks

The entire contextual actions dialog is considered a region. Design the information blocks of the dialog according to these guidelines:

  • You can include additional fields in each information block, provided that the dialog remains sized to fit within the maximum secondary window measurements (512 x 384).
  • Ensure that a dialog remains visually balanced as you add information and actions. Work with your UX POC to determine the design of the dialog.
  • See Dialog Size section in this guideline below.

Icon Button Groupings

Follow these guidelines when grouping icon buttons within the contextual action dialog:

  • Locate actions that pertain to the whole object in the lower-left side of the dialog.
  • Locate actions that pertain to individual fields next to those fields.
Figure 14. This dialog illustrates the placement of icon buttons

Dialog Size

The dialog automatically resizes based on its content. According to the Secondary Window Usage Guideline, the recommended maximum secondary window measurements are 512 x 384.

Font Styles

The object name (person name, company name) should use page title style (top level of header component) since it is in fact a page title for the content of the dialog. For the subtitle (job title, etc), use the instructional text style.

Context (Right-Click) Menus

Context menus on contextual-actions-enabled fields will be unaffected by contextual actions and should comply with existing guidelines. (See Context Menus in the Menu Guideline )


Figure 15. The contextual actions dialog should not be used if it includes any actions that require the user to update or refresh the launching page. Note that this is an exception case since contextual actions should rarely include editable fields.

This problem can be avoided using any of the following:

  • Consuming teams should not enable contextual action dialogs where they contain fields that duplicate those on the launching page.
  • Providers should give consumer teams the ability to pass parameters that can turn off editable fields in the contextual actions dialog that are also on the launching page.
  • Providers should avoid using editable fields in the contextual actions dialog.

Mandatory and Optional Objects

Consumers must include the contextual actions whenever a mandatory contextual action object is exposed in their application.

Customization by Customer

No customer configuration or customization is currently planned.

No Records Found

Providers incorporating glyphs in their dialogs must hide the glyph if no data can be shown for an object type in a particular context persistently (e.g. if module is not installed).

Consumers must ensure that the contextual action dialog is not opened if the field contains invalid data; in such cases user should see the appropriate invalid entry error message.  In cases where the field value is valid but nothing can be displayed (e.g. data used to be correct but doesn’t exist anymore), consuming team provides a message specific to the reason for data not being present.

Note: It doesn't make sense to display a No Records Found message ("No records match your entry. Ensure your entry is correct and try again.").  If the field doesn't contain valid information, then no glyph should appear and changing the entry won't affect the outcome.

Use cases

  1. User enters valid value, changes focus, value is validated (autosubmit), glyph shows up
    outcome: user clicks i-pop to display correct dialog
  2. User enters invalid value, changes focus, value is validated
    outcome: user receives invalid entry error message
  3. User enters invalid value over a previously valid value and then clicks i-pop
    outcome: user receives invalid entry error message
  4. Field value is valid, but nothing can be displayed...e.g. data used to be correct, doesn't exist anymore. 
    outcome: consuming team provides a message specific to the reason for data not being present.


Contextual Actions is not keyboard accessible in v1 since information found in each Contextual Actions dialog is accessible via other pages.  The information displayed is not critical to the current task and is only secondary/alternative info.

A contrast check on the glyph color passed this contrast checker when used as large text. Since the large text sample in the checker was one pixel thinner than the glyph itself, the color has been assumed to pass. Contrast checkers are made for text, not graphics, so this was the only way to derive this information.

Related Documentation
Return to Top

Here are links to some related documentation:

About Oracle | Legal Notices | Terms of Use | Your Privacy Rights