Element: <oj-messages>

Oracle® JavaScript Extension Toolkit (JET)
7.1.0

F18183-01

Signature:

class ojMessages

QuickNav

Attributes

JET Custom Elements

JET components are implemented as custom HTML elements. In addition to the component attributes documented in this page, JET components also support standard HTML global attributes like id and aria-label.

The JET data binding syntax can be used to define both component and global attributes through the use of dynamically evaluated expressions. All attributes (component and global) support attribute-level binding by prefixing the attribute name with ":" (e.g. :id="[...]"). When using attribute-level binding, all expression values are treated as strings. Additionally, component attributes support property-level binding by using the attribute name directly with no ":" prefix. When using property-level binding, the expressions should evaluate to the types documented by the corresponding attributes. Property-level binding is strongly recommended over attribute-level binding for component attributes.

A detailed description of working with custom HTML elements can be found in: JET Custom Element Usage.



PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

Version:
  • 7.1.0
Since:
  • 5.0.0
Module:
  • ojmessages

Module usage

See JET Module Loading for an overview of module usage within JET.

Typescript Import Format
//To typecheck the element APIs, import as below.
import {ojMessages} from "ojs/ojmessages";

//For the transpiled javascript to load the element's module, import as below
import "ojs/ojmessages";

JET In Typescript

A detailed description of working with JET elements and classes in your typescript project can be found at: JET Typescript Usage.


JET Messages

Description:

Manages the layout and display of one or more messages. The only supported component child element of oj-messages is oj-message.

Layouts

Messages can be shown in these layouts

  • Inlined to the page content
  • Overlayed on the page content, positioned to the top of the page by default
  • As notifications, positioned to the top-end corner of the page by default
Inlined messages will push the page contents when a new message is shown and could scroll out of the view when user scrolls the page. Overlayed or notification style messages are usually positioned relative to the window, will assume a fixed position and will remain visible when the user scrolls the page. Overlayed or notification messages can be positioned relative to another element in the page, in which case the messages follow that element upon page scroll. Inline and overlay layouts are suitable for messages pertaining to the page or region of the page, or relating to the task the user performed on the page. Notification layout is suitable for messages that arrive asynchronously to the application or to communicate alerts to users. Examples below shows the three layouts.

<!-- Inline: Do not specify the 'position', set 'display' to 'general' -->
<oj-messages id="inlineMessages" messages="[[serviceRequestMessages]]" display="general">
</oj-messages>

<!-- Overlay: Set 'position' to an empty or a structured object, set 'display' to 'general' -->
<oj-messages id="overlayMessages" messages="[[serviceRequestMessages]]" position="{}" display="general">
</oj-messages>

<!-- Notification: Set 'position' to an empty or a structured object, set 'display' to 'notification' -->
<oj-messages id="notificationMessages" messages="[[emailMessages]]" position="{}" display="notification">
</oj-messages>

Syntaxes

Messages can be defined as below followed by examples

  • Include an oj-message child for every message to be shown. This is suitable for case when the messages are static and in small numbers
  • Include oj-message child, wrap it inside of a for-each binding. This is suitable for case where one or more message sources need to be displayed in a single messages element
  • Use the simple syntax to directly bind a collection to the 'messages' attribute of oj-messages. This is a convenient syntax and suitable when a single message source is used

<!-- Including oj-message children -->
<oj-messages id="inlineMessages">
  <oj-message message='{"summary": "Some summary", "detail": "Some detail", "autoTimeout": 5000}'></oj-message>
  <oj-message message="[[surveyInstructions]]"></oj-message>
  <oj-message message="[[surveySubmitConfirmation]]"></oj-message>
</oj-messages>

<!-- For-each bound oj-message children -->
<oj-messages id="pageOverlayMessages" position="{}" display="notification">
  <oj-bind-for-each data="[[serviceRequestStatusUpdateMessages]]">
    <template>
      <oj-message message="[[$current.data]]"></oj-message>
    </template>
  </oj-bind-for-each>
  <oj-bind-for-each data="[[criticalIncidentMessages]]">
    <template>
      <oj-message message="[[$current.data]]"></oj-message>
    </template>
  </oj-bind-for-each>
</oj-messages>

<!-- Collection bound simple syntax, no need to specify oj-message children -->
<oj-messages id="notificationMessages" messages="[[emailMessages]]" position="{}" display="notification">
</oj-messages>

Reparenting

When the messages region is disclosed as a popup (position property defined), it will be reparented in the document and reparented back when all contained messages are closed. The location of the messages within the document will be in context of where it is defined. This is different than other types of popups where their reparenting location depends on the context they are used. The stacking context of the messages region will be defined by the "oj-messages-layer" style class. The messages region that has active focus will be assigned a greater z-index value. This is applied to the messages's layer by way of the "oj-focus-within" pseudo selector applied with "oj-messages-layer" selector. The page author has control over z-index weights by way of the "oj-messages-layer" selector.

Keyboard End User Information

Target Key Action
Focus within Messages Tab or Shift + Tab Navigate the content of the messages region.
F6 Moves focus back to the last focused element outside the messages region.
Esc Moves focus back to the last focused element outside the messages region.
Focus outside Messages F6 Move focus to the first message within the more recently disclosed messages region.

Styling

The following CSS classes can be applied by the page author as needed.

Class Description
oj-messages-inline-remove-bottom-border Inline messages will include a bottom border so that the messages section is demarcated from the contents below it. If this border is not desirable for certain page layouts, it can be removed by setting this marker class on oj-messages.

Note: Application logic should not interact with the component's properties or invoke its methods until the BusyContext indicates that the component is ready for interaction.

Slots

JET components that allow child content support slots. Please see the slots section of the JET component overview doc for more information on allowed slot content and slot types.

Default

The <oj-messages> element accepts only <oj-message> element as children for the default slot. The default slot contents are rendered only if the 'messages' attribute on <oj-messages> is not set. If the 'messages' attribute is set <oj-message> children are automatically stamped for each message data in the collection.

Since:
  • 5.0.0

messageTemplate

PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

The messageTemplate slot is used to specify the template for rendering each message in the oj-messages. The slot must be a <template> element. The default template will display the oj-message children to best suit the display type of the oj-messages. This template slot will be applied only if the 'messages' attribute on oj-messages> is set. The content of the template must be an oj-message element.

When the template is executed for each message, it will have access to the binding context containing the following properties:

  • $current - an object that contains information for the current message. (See the table below for a list of properties available on $current)
  • alias - if 'data-oj-as' attribute was specified on the <template> element, the value will be used to provide an application-named alias for $current.
Properties of $current:
Name Type Description
componentElement Element The <oj-messages> custom element.
data oj.ojMessage.Message The data for the current message being rendered.
Since:
  • 6.2.0

Attributes

display :"general"|"notification"

Specifies the display purpose of messages. The valid values for display are general and notification. General messages are commonly rendered at the page level or section level, relating to the task the user performed. Notification messages are typically used for reporting asynchronous events, or to communicate some background activity.

The presentation of the message is inline by default. However, when a oj.ojMessages#positionproperty is provided, the presentation will be an overlay. The alignment of the overlay will default based on the display property. The defaults are defined by the theme.
Supported Values:
Value Description
"general" messages pertaining to the page or region of the application
"notification" often used for communicating alerts arriving asynchronously
Default Value:
  • "general"
Since:
  • 5.0.0
Names
Item Name
Property display
Property change event displayChanged
Property change listener attribute (must be of type function) on-display-changed

display-options :oj.ojMessage.DisplayOptions

Specifies the display options for contents of all the messages specified for the oj.ojMessages#messages attribute.

Since:
  • 6.1.0
Names
Item Name
Property displayOptions
Property change event displayOptionsChanged
Property change listener attribute (must be of type function) on-display-options-changed

display-options.category :"header"|"auto"|"none"

Specifies display option for oj.ojMessage#message.category text in all the messages specified for the oj.ojMessages#messages attribute.

Supported Values:
Value Description
"auto" the component decides whether and where the oj.ojMessage#message.category text is displayed. The behavior is same as 'header' option, but may change in future releases.
"header" if the oj.ojMessage#message.category property is specified, its value will be displayed in the header region of the message next to message icon. If oj.ojMessage#message.category property is not specified, a translated text corresponding to the value of the oj.ojMessage#message.severity property will be displayed.
"none" the oj.ojMessage#message.category text will not be displayed
Default Value:
  • "auto"
Names
Item Name
Property displayOptions.category

messages :(Array.<oj.ojMessage.Message>|null|oj.DataProvider.<any, oj.ojMessage.Message>)

Specifies the collection of structured message data used to display the individual messages. Instead of providing multiple oj-message as children, this property can be used to conveniently specify the required data as a single collection. Individual message will be automatically created based on this data. See oj.ojMessage.Message for message values.

More information about the structured 'Message' data can be found in documentation for 'message' attribute of oj-message element.

The collection can be two types:
  • an array of oj.ojMessage.Message objects.
  • oj.ArrayDataProvider of oj.ojMessage.Message objects. Look at oj.ArrayDataProvider for more available options.
  • Default Value:
    • null
    Since:
    • 5.0.0
    Names
    Item Name
    Property messages
    Property change event messagesChanged
    Property change listener attribute (must be of type function) on-messages-changed

    position :(oj.ojMessages.Position|null)

    The position property defines the presentation style. The default presentation is inline, defined by a null position property value. When a value is provide for the property, the presentation style will be an overaly "popup". The aligment of the overaly is defined by the position sub-properties.

    Default position sub-properites are extended by the provided value. Defaults vary based on the display property and provided by theme. The position property is used to establish the location where the messages popup overlay will appear relative to another element.

    The "my" and "at" properties defines aligment points relative to the popup and other element. The "my" property represents the popups alignment where the "at" property represents the other element that can be identified by "of" or defauts to the launcher when the popup opens. The values of these properties describe horizontal and vertical alignments.

    Names
    Item Name
    Property position
    Property change event positionChanged
    Property change listener attribute (must be of type function) on-position-changed

    position.at :Object

    Defines which position on the target element ("of") to align the positioned element against.
    Names
    Item Name
    Property position.at

    position.at.horizontal :"start"|"end"|"left"|"center"|"right"

    Defines the horizontal alignment of what the messges overlay is aligned to.
    Supported Values:
    Value Description
    "center"
    "end" evaluates to "right" in LTR mode and "left" in RTL mode.
    "left"
    "right"
    "start" evaluates to "left" in LTR mode and "right" in RTL mode.
    Names
    Item Name
    Property position.at.horizontal

    position.at.vertical :"top"|"center"|"bottom"

    Defines the vertical alignment of what the messages overlay is aligned to.
    Supported Values:
    Value
    "bottom"
    "center"
    "top"
    Names
    Item Name
    Property position.at.vertical

    position.collision :"flip"|"fit"|"flipfit"|"none"

    Rule for alternate alignment.
    Supported Values:
    Value Description
    "fit" shift the element away from the edge of the window.
    "flip" the element to the opposite side of the target and the collision detection is run again to see if it will fit. Whichever side allows more of the element to be visible will be used.
    "flipfit" first applies the flip logic, placing the element on whichever side allows more of the element to be visible. Then the fit logic is applied to ensure as much of the element is visible as possible.
    "none" no collision detection.
    Names
    Item Name
    Property position.collision

    position.my :Object

    Defines which edge on the messages overlay to align with the target ("of") element.
    Names
    Item Name
    Property position.my

    position.my.horizontal :"start"|"end"|"left"|"center"|"right"

    Defines the horizontal alignment of the messages overlay.
    Supported Values:
    Value Description
    "center"
    "end" evaluates to "right" in LTR mode and "left" in RTL mode.
    "left"
    "right"
    "start" evaluates to "left" in LTR mode and "right" in RTL mode.
    Names
    Item Name
    Property position.my.horizontal

    position.my.vertical :"top"|"center"|"bottom"

    Defines the vertical alignment of the messages overlay.
    Supported Values:
    Value
    "bottom"
    "center"
    "top"
    Names
    Item Name
    Property position.my.vertical

    position.of :string

    Which element to position the messages overlay against. If the value is a string, it should be a selector or the literal string value of window. Otherwise, a point of x,y. When a point is used, the values are relative to the whole document. Page horizontal and vertical scroll offsets need to be factored into this point - see UIEvent pageX, pageY.
    Names
    Item Name
    Property position.of

    position.offset :Object

    Defines a point offset in pixels from the ("my") alignment.
    Names
    Item Name
    Property position.offset

    position.offset.x :number

    Horizontal aligment offset.
    Names
    Item Name
    Property position.offset.x

    position.offset.y :number

    Vertical alignment offset.
    Names
    Item Name
    Property position.offset.y

    translations :Object

    A collection of translated resources from the translation bundle, or null if this component has no resources. Resources may be accessed and overridden individually or collectively, as seen in the examples.

    If this component has translations, their documentation immediately follows this doc entry.

    Since:
    • 5.0.0
    Names
    Item Name
    Property translations
    Property change event translationsChanged
    Property change listener attribute (must be of type function) on-translations-changed

    (nullable) translations.aria-live-region :Object

    Various contextual live region texts that oj-messages component will use for accessibility purpose.

    See the translations attribute for usage examples.

    Since:
    • 5.0
    Names
    Item Name
    Property translations.ariaLiveRegion

    (nullable) translations.aria-live-region.navigation-from-keyboard :string

    Text to guide keyboard users navigate to prior focussed element when the messages region gains focus.

    See the translations attribute for usage examples.

    Default Value:
    • "Entering messages region. Press F6 to navigate back to prior focused element."
    Since:
    • 5.0
    Names
    Item Name
    Property translations.ariaLiveRegion.navigationFromKeyboard

    (nullable) translations.aria-live-region.navigation-to-keyboard :string

    Text to guide keyboard users navigate to new displayed messages when focus is outside the messages popup.

    See the translations attribute for usage examples.

    Default Value:
    • "Messages region has new messages. Press F6 to navigate to the most recent message region."
    Since:
    • 5.0
    Names
    Item Name
    Property translations.ariaLiveRegion.navigationToKeyboard

    (nullable) translations.aria-live-region.navigation-to-touch :string

    Text to guide touch screen (voice-over) users navigate to new displayed messages when focus is outside the messages popup.

    See the translations attribute for usage examples.

    Default Value:
    • "Messages region has new messages. Use the voice-over rotor to navigate to the messages landmark."
    Since:
    • 5.0
    Names
    Item Name
    Property translations.ariaLiveRegion.navigationToTouch

    (nullable) translations.aria-live-region.new-message :string

    Text representing the new displayed message. This text may contain tokens '{category}' and '{summary}', which will be replaced by the corresponding sub-property values in the data for the new message.

    See the translations attribute for usage examples.

    Default Value:
    • "Message category {category}. {summary}."
    Since:
    • 5.0
    Names
    Item Name
    Property translations.ariaLiveRegion.newMessage

    (nullable) translations.label-landmark :string

    Label for the landmark region for accessibility.

    See the translations attribute for usage examples.

    Default Value:
    • "Messages"
    Since:
    • 5.0
    Names
    Item Name
    Property translations.labelLandmark

    Methods

    close(message) → {void}

    Closes the specified message regardless of the oj.ojMessage#message.autoTimeout or oj.ojMessage#message.closeAffordance properties. The message argument is a required argument, must be of type oj.ojMessage#message, and must be the same object instance that was used to create and show the oj-message.

    Closing a message changes the visibility to hidden. If the message is defined by an instance in the oj.ojMessages#messages collection, the close operation will not remove the item from the backing model. Application logic needs to listen for the oj.ojMessage#event:close event bubbling up from the underlying oj-message child to remove from the backing collection.

    Parameters:
    Name Type Description
    message oj.ojMessage.Message the message to be closed
    Since:
    • 5.0.0
    Returns:
    Type
    void

    closeAll(closeFilter) → {void}

    Closes child messages matching the closeFilter callback criteria. The closeFilter callback is an optional argument. If not specified, all child messages will be closed. If filter is specified, object of type oj.ojMessage#message corresponding to each child will be passed to the closeFilter function. A return value of true will result in calling oj.ojMessage#close for the message. Otherwise, the message will remain in its current state.

    Closing a message changes the visibility to hidden. If the message is defined by an instance in the oj.ojMessages#messages collection, the close operation will not remove the item from the backing model. Application logic needs to listen for the oj.ojMessage#event:close event bubbling up from the underlying oj-message child to remove from the backing collection.

    Parameters:
    Name Type Argument Description
    closeFilter (message: ojMessage.Message) => boolean <optional>
    an optional callback function that will be passed an instance of type oj.ojMessage#message for each child oj-message. If closeFilter returns true, the associated oj-message will be closed. Returning false will exclude the child message from closure. If a closeFilter is not passed, all child messages will be closed.
    Since:
    • 5.0.0
    Returns:
    Type
    void

    getProperty(property) → {any}

    Retrieves a value for a property or a single subproperty for complex properties.
    Parameters:
    Name Type Description
    property string The property name to get. Supports dot notation for subproperty access.
    Since:
    • 5.0.0
    Returns:
    Type
    any

    setProperties(properties) → {void}

    Performs a batch set of properties.
    Parameters:
    Name Type Description
    properties Object An object containing the property and value pairs to set.
    Since:
    • 5.0.0
    Returns:
    Type
    void

    setProperty(property, value) → {void}

    Sets a property or a single subproperty for complex properties and notifies the component of the change, triggering a [property]Changed event.
    Parameters:
    Name Type Description
    property string The property name to set. Supports dot notation for subproperty access.
    value any The new value to set the property to.
    Since:
    • 5.0.0
    Returns:
    Type
    void

    Type Definitions

    Position

    Properties:
    Name Type Argument Description
    my oj.ojMessages.PositionAlign <optional>
    Defines which edge on the popup to align with the target ("of") element.
    at oj.ojMessages.PositionAlign <optional>
    Defines which position on the target element ("of") to align the positioned element against.
    offset oj.ojMessages.PositionPoint <optional>
    Defines a point offset in pixels from the ("my") alignment.
    of string | oj.ojMessages.PositionPoint <optional>
    Which element to position the popup against. If the value is a string, it should be a selector or the literal string value of window. Otherwise, a point of x,y. When a point is used, the values are relative to the whole document. Page horizontal and vertical scroll offsets need to be factored into this point - see UIEvent pageX, pageY.
    collision "flip" | "fit" | "flipfit" | "none" <optional>
    Rule for alternate alignment.

    • "flip" the element to the opposite side of the target and the collision detection is run again to see if it will fit. Whichever side allows more of the element to be visible will be used.
    • "fit" shift the element away from the edge of the window.
    • "flipfit" first applies the flip logic, placing the element on whichever side allows more of the element to be visible. Then the fit logic is applied to ensure as much of the element is visible as possible.
    • "none" no collision detection.

    PositionAlign

    Properties:
    Name Type Argument Description
    vertical "top" | "bottom" | "center" <optional>
    Vertical alignment.
    horizontal "start" | "end" | "left" | "center" | "bottom" <optional>
    Horizontal alignment.

    • "start" evaluates to "left" in LTR mode and "right" in RTL mode.
    • "end" evaluates to "right" in LTR mode and "left" in RTL mode.

    PositionPoint

    Properties:
    Name Type Argument Description
    x number <optional>
    Horizontal aligment offset.
    y number <optional>
    Vertical alignment offset.