Element: <oj-message>

Oracle® JavaScript Extension Toolkit (JET)
17.0.0
F92240-01

Since:
  • 5.0.0
Module:
  • ojmessage

QuickNav

Slots

Attributes

Events

Methods

Type Definitions

Other Topics


JET Message

Description:

Displays a message. All oj-message elements in a page must have an oj-messages element as its parent.

<oj-message id="simpleMessage" message="[[messageData]]">
</oj-message>

Accessibility

The oj.ojMessage#message.sound property is an accessibility feature for playing a sound when a message is opened. This property defaults to "none", and can be enabled by setting it to "defaults" or by providing URL to an audio file of a format that the browser supports. An accessible application must provide a way for users to enable sound on a settings or preferences page. Some browsers will have auto-play disabled by default, enabling it may require adjusting the browser settings.

Touch End User Information

Target Gesture Action
Message Swipe Right, Swipe Up Close the message
Message Close Icon Tap Close the message

Keyboard End User Information

Target Key Action
Message Esc Close the message
Message Close Icon Enter or Space Close the message


Usage

Signature:

interface MessageElement

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

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

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.


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.

detail

The detail slot is for the message's detail area. The <oj-message> element accepts DOM nodes as children with the detail slot. This slot is useful to add links or buttons to the detail area. The default template will just display the text value of 'message.detail' property for any message.

Since:
  • 6.2.0

Attributes

display-options :oj.ojMessage.DisplayOptions

Specifies the display options for contents of the message.

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 this message.

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

message :oj.ojMessage.Message

Structured data specifying essential information to display a message on the UI.

Since:
  • 5.0.0
Names
Item Name
Property message
Property change event messageChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-message-changed

message.auto-timeout :number

Specifies the number of milliseconds for which duration the message will be shown before it is closed automatically.

This attribute can take the number of millisecond or special number values -1 and 0. If the value is set to "-1", auto-close will be turned off. If the value is set to "0", application wide value for autoTimeout as specified in a theming variable will be used.

Default Value:
  • -1
Since:
  • 5.0.0
Names
Item Name
Property message.autoTimeout

message.category :string

Specifies text representing the message category which is shown next to the message icon

If this attribute is not specified, a translated text corresponding to value of message.severity attribute will be rendered.

Default Value:
  • ""
Since:
  • 5.0.0
Names
Item Name
Property message.category

message.close-affordance :"none"|"defaults"

Specifies the UI affordance provided to end users to be able to close the message.

Supported Values:
Value Description
defaults Use implicit affordance to best suit the native theme, efficient use of available space, and screen touch capabilities.

A close 'X' icon is displayed in all cases except in the case when the message is set to auto-timeout when using mobile themes. The display of the close icon can be further controlled by using the theme variables as noted below. See keyboard and touch end user information sections in this document for interaction options.
none No UI affordance is provided to close the message. Application has to call the close() method to dismiss the message.
Default Value:
  • "defaults"
Since:
  • 5.0.0
Names
Item Name
Property message.closeAffordance

message.detail :string

Specifies detail text for the message.

Default Value:
  • ""
Since:
  • 5.0.0
Names
Item Name
Property message.detail

message.icon :string

Specifies the URL for the custom image to be used as an icon representing the message.

The icon will be rendered as background image inside a container that is set to size of 16px*16px in alta-web theme and 10px*20px for all other themes, therefore, the icon chosen must fit this dimensions.

If this attribute is not specified, a suitable icon corresponding to value of message.severity will be rendered.

Default Value:
  • ""
Since:
  • 5.0.0
Names
Item Name
Property message.icon

message.severity :"error"|"warning"|"confirmation"|"info"|"none"

Specifies the severity of message.

Supported Values:
Value Description
confirmation Confirmation message.
error Error level message.
info Informational message.
none Message status level not applicable.
warning Warning level message.
Default Value:
  • "none"
Since:
  • 5.0.0
Names
Item Name
Property message.severity

message.sound :string

Specifies the sound to be played when a message is opened. Sound is an accessibility feature required for low vision users who view a zoomed section of the UI. Because messages may be shown outside of the zoomed section, such users require sound to be played to notify of new messages.

This attribute can take a URL of the audio file for the custom sound to be played. The supported formats are mp3, wav and ogg. Browser support should also be considered while choosing the format of the audio file. Literal string values "defaults" and "none" can also be used for this attribute. If the value is set to "none", then the sound will be disabled. If the value is set to "defaults", then a default sound is played.

The default sound uses Web Audio APIs, which is not yet supported by some browsers, default sound will not be played in such browsers. Sound will not be played in browsers where auto play is not enabled. Some of the browsers do not allow auto play, while other browsers may provide a user preference to enable it.

Default Value:
  • "none"
Since:
  • 5.0.0
Names
Item Name
Property message.sound

message.summary :string

Specifies summary text for the message.

Default Value:
  • ""
Since:
  • 5.0.0
Names
Item Name
Property message.summary

message.timestamp :string

Specifies timestamp for the message to be displayed in the message header.

timestamp could represent the date and time at which the message was created, or otherwise could pertain to the event for which the message was created. For example, a timestamp for an upcoming meeting could be set in the future, whereas a timestamp for a missed message could be set in the past.

This specified value must be an ISOString. A default converter is used to convert and format the value suitable for displaying in the message. This default convertor used such will be an implementation detail and could change in future.

Default Value:
  • ""
Since:
  • 5.0.0
Names
Item Name
Property message.timestamp

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.categories :Object

Category text to be displayed for the messages of different severity levels.

See the translations attribute for usage examples.

Since:
  • 5.0
Names
Item Name
Property translations.categories

(nullable) translations.categories.confirmation :string

Category text for the 'confirmation' severity level.

See the translations attribute for usage examples.

Default Value:
  • "Confirmation"
Since:
  • 5.0
Names
Item Name
Property translations.categories.confirmation

(nullable) translations.categories.error :string

Category text for the 'error' severity level.

See the translations attribute for usage examples.

Default Value:
  • "Error"
Since:
  • 5.0
Names
Item Name
Property translations.categories.error

(nullable) translations.categories.info :string

Category text for the 'info' severity level.

See the translations attribute for usage examples.

Default Value:
  • "Information"
Since:
  • 5.0
Names
Item Name
Property translations.categories.info

(nullable) translations.categories.none :string

Category text when there is no severity level.

See the translations attribute for usage examples.

Default Value:
  • "None"
Since:
  • 14.1.0
Names
Item Name
Property translations.categories.none

(nullable) translations.categories.warning :string

Category text for the 'warning' severity level.

See the translations attribute for usage examples.

Default Value:
  • "Warning"
Since:
  • 5.0
Names
Item Name
Property translations.categories.warning

(nullable) translations.label-close-icon :string

Label for the message close button.

See the translations attribute for usage examples.

Default Value:
  • "Close"
Since:
  • 5.0
Names
Item Name
Property translations.labelCloseIcon

Events

ojClose

Triggered after the message is closed through user interaction or due to calling close() method.
Properties:

All of the event payloads listed below can be found under event.detail. See Events and Listeners for additional information.

Name Type Description
message oj.ojMessage.Message The message that was closed.
Since:
  • 5.0.0

Methods

close : {void}

Closes the message.
Since:
  • 5.0.0
Fires:
  • oj.ojMessage#event:ojClose
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

DisplayOptions

Properties:
Name Type Argument Description
category "header" | "none" | "auto" <optional>
 Defines display option for the category text in the message.

Message

Properties:
Name Type Argument Description
autoTimeout number <optional>
 Defines the time after which the message is to be closed automatically.
category string <optional>
 Defines category text of the message.
closeAffordance "none" | "defaults" <optional>
 Defines UI affordance provided to close the message.
detail string <optional>
 Defines detail text of the message.
icon string <optional>
 Defines the icon representing the message.
severity "error" | "warning" | "confirmation" | "info" | "none" <optional>
 Defines severity of the message.
sound string <optional>
 Defines the sound to be played when message is open.
summary string <optional>
 Defines summary text of the message.
timestamp string <optional>
 Defines timestamp of the message.