Element: <oj-messages>

Oracle® JavaScript Extension Toolkit (JET)
17.1.0
G12196-01

Since:
  • 5.0.0
Module:
  • ojmessages

Note: This component is in maintenance mode. Suggested alternatives: <oj-c-message-banner>, <oj-c-message-toast>. For help updating an existing application, see the migration section.

QuickNav

Slots

Attributes

Methods

Type Definitions

Other Topics


JET Messages

Description:

Manages the layout and display of one or more messages.

Syntax

Messages can be defined using a simple syntax to directly bind a DataProvider to the 'messages' attribute of oj-messages as shown below.

Note that the use of inlined oj-message children inside of oj-messages is deprecated. Applications should directly databind 'messages' attribute of oj-messages instead. Using oj-message inside of the 'messageTemplate' slot to define the template is still valid. 


<oj-messages id="pageMessages" messages="[[messagesDataProvider]]">
</oj-messages>

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>

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.

Migration (Message Toast)

Read about current Core Pack limitations to decide when to migrate.
Please make note of the following:

To migrate from oj-messages to oj-c-message-toast, you need to revise the import statement and references to oj-c-message-toast in your app. Please note the changes between the two components below.

Display attribute

In oj-messages, the messages are rendered as toasts if the display attribute is set to "notification". But, the oj-c-message-toast is a dedicated component for rendering messages as toasts. So, this attribute is not needed.

Display Options attribute

This attribute allows one to configure whether or not to show the category text in the oj-messages component. But, in the oj-c-message-toast component, the category texts are not supported and thus no need for this attribute.

Messages attribute

The oj-c-message-toast component uses data attribute instead of the messages attribute. The new data attribute only supports having a DataProvider as its value. If you were using an array for the messages attribute, you need to wrap it in a DataProvider when migrating to the new component. Also, the new attribute is a required attribute. So, if you were not setting the messages attribute, you will still need to set the data attribute in the new component to a DataProvider but it can be initialized with an empty array.

Position attribute

In the oj-c-message-toast component this attribute will take a string instead of an object. In the new component, the messages are always positioned with respect to the widow and thus it only takes the following string values for this property:

  • "top"
  • "top-left"
  • "top-start"
  • "top-right"
  • "top-end"
  • "bottom"
  • "bottom-left"
  • "bottom-start"
  • "bottom-right"
  • "bottom-end"
The offset property of the position object is moved as a separate attribute.

Position.offset property

If one were setting offset using the position.offset property of the oj-messages component, the same can be done using the offset attribute of the oj-c-message-toast component. One can either set it to a number, which will then be used for both horizontal and vertical offset, or set it to an object with horizontal and vertical properties set.

Translations attribute

Per instance translations object is not supported in the new oj-c-message-toast component. Use the translations bundle instead.

ojClose event

In oj-c-message-toast component, ojClose event is triggered when one tries to close a message in the page. But, this will not automatically close the message on the UI. The application needs to listen to this event and remove the corresponding item from DataProvider. This will in turn remove the messages from the UI.

Close methods

The oj-c-message-toast component does not support close and closeAll methods. To close a single message or all messages, simply remove the corresponding items from the DataProvider.

messageTemplate

The messageTemplate or the usage of oj-message component is not supported in the oj-c-message-toast component. Instead, one can have any number of arbitrarily named template slots. In these templates, one can directly provide the content without having to wrap them in an oj-message component. Then using the detail-template-value attribute, one can specify which template will be used for which message. In the similar way, one can also configure the start-icon of the component using the icon-template-value attribute.

Message type

The oj-c-message-toast component uses the MessageToastItem type for the items in the DataProvider. Please note the changes in properties below:

  • autoTimeout - changed to "on" | "off" | number. Use 'on' instead of 0 and 'off' instead of -1.
  • category - not supported as it is not an approved redwood-pattern
  • closeAffordance - changed to "on" | "off". Use 'off' instead of 'none' and leave the attribute unset instead of 'defaults'.
  • icon - not supported as it is not an approved redwood-pattern
  • timestamp - not supported as it is not an approved redwood-pattern


Usage

Signature:

interface MessagesElement

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

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

For additional information visit:

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.


Styling Classes

.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.
Example
<oj-messages class="oj-messages-inline-remove-bottom-border">
  <!-- Content -->
</oj-messages>
.oj-messages-outlined
Inline messages (Banners) can be either Edge-to-Edge or Outlined. By default, the inline messages are rendered as Edge-to-Edge Banner messages. If Outlined Banner messages are preferred instead, add oj-messages-outlined class on the oj-messages element.
Since:
  • 10.0.0
Example
<oj-messages class="oj-messages-outlined">
  <!-- Content -->
</oj-messages>

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.

Note that the use of inlined oj-message children inside of oj-messages is deprecated. Applications should directly databind 'messages' attribute of oj-messages instead. Using oj-message inside of the 'messageTemplate' slot to define the template is still valid.

Since:
  • 5.0.0

messageTemplate

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 oj.ojMessages.MessageTemplateContext or 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, see Events and Listeners for additional information.) 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, see Events and Listeners for additional information.) 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.

In Redwood theme, showing the category text is an anti-pattern. Set this attribute to "none".

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|DataProvider.<any, oj.ojMessage.Message>)

Specifies the collection of structured message data used to display the individual messages. 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 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, see Events and Listeners for additional information.) 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 alignment 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 alignment 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, see Events and Listeners for additional information.) 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 messages 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 alignment 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, see Events and Listeners for additional information.) 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}' ,'{summary}' and '{detail}', 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}. {detail}."
    Since:
    • 5.0
    Names
    Item Name
    Property translations.ariaLiveRegion.newMessage

    (nullable) translations.aria-live-region.no-detail :string

    Text to be used in the live region when there is no detail.

    See the translations attribute for usage examples.

    Default Value:
    • "Detail is not available"
    Since:
    • 14.1.0
    Names
    Item Name
    Property translations.ariaLiveRegion.noDetail

    (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

    MessageTemplateContext

    Properties:
    Name Type Description
    componentElement Element The <oj-messages> custom element.
    data oj.ojMessage.Message The data for the current message being rendered.

    Position

    Properties:
    Name Type Argument Description
    at oj.ojMessages.PositionAlign <optional>
    		 Defines which position on the target element ("of") to align the positioned element against.
    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.
    my oj.ojMessages.PositionAlign <optional>
    		 Defines which edge on the popup to align with the target ("of") element.
    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.
    offset oj.ojMessages.PositionPoint <optional>
    		 Defines a point offset in pixels from the ("my") alignment.

    PositionAlign

    Properties:
    Name Type Argument Description
    horizontal "start" | "end" | "left" | "center" | "right" <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.
    vertical "top" | "bottom" | "center" <optional>
    		 Vertical alignment.

    PositionPoint

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