Element: <oj-message>

Oracle® JavaScript Extension Toolkit (JET)
5.0.0

E90577-01

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:
  • 5.0.0
Since:
  • 5.0.0
Module:
  • ojmessage

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 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

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.

Attributes

message :oj.ojMessage.Message

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

Default Value:
  • {"icon": "", 'category': "", "severity": "none", "summary": "", "detail": "", "autoTimeout": -1, "closeAffordance": "defaults", "sound": "none"}
Since:
  • 5.0.0
Names
Item Name
Property message
Property change event messageChanged
Property change listener attribute (must be of type function) on-message-changed
Examples

Initialize the element with message attribute:

<!-- Binding message attribute to a structured object -->
<oj-message message="[[myMessageData]]"></oj-message>

<!-- Setting message using JSON notation -->
<oj-message message='{"severity": "error", "summary": "Some summary", "detail": "Some detail"}'></oj-message>

<!-- Setting the message sub-attributes -->
<oj-message message.severity="error" message.summary="Some summary" message.detail="Some detail"></oj-message>

Get or set the message property after initialization:

// getter
var message = myMessage.message;

// setter - sets all sub-properties (missing sub-properties are defaulted)
myMessage.message = {
    severity: "error",
    summary: "Some summary",
    detail: "Some detail"
};

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
Examples

Initialize the element with message.auto-timeout attribute:

<oj-message message.auto-timeout="3000" message.summary="Some summary"></oj-message>

Get or set the message.autoTimeout property after initialization:

// getter
var autoTimeout = myMessage.getProperty("message.autoTimeout");

// setter
myMessage.message.autoTimeout = 3000;

The default auto-timeout value can be set at application level using this theme variable (SCSS) :

$messageAutoTimeoutOptionDefault: 5000 !default;

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
Examples

Initialize the element with message.category attribute:

<oj-message message.category="Service Request" message.summary="New SR - Escalated"></oj-message>

Get or set the message.category property after initialization:

// getter
var category = myMessage.getProperty("message.category");

// setter
myMessage.setProperty("message.category", "Service Request");

message.close-affordance :string

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

Supported Values:
Name Type Description
"defaults" string use implicit affordance to best suit the native theme and screen touch capabilities. See keyboard and touch end user information sections in this document.
"none" string 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
Examples

Initialize the element with message.close-affordance attribute:

<oj-message message.close-affordance="none" message.summary="Some summary"></oj-message>

Get or set the message.closeAffordance property after initialization:

// getter
var closeAffordance = myMessage.getProperty("message.closeAffordance");

// setter
myMessage.setProperty("message.closeAffordance", "none");

message.detail :string

Specifies detail text for the message.

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

Initialize the element with message.detail attribute:

<oj-message message.detail="Some detail" message.summary="Some summary"></oj-message>

Get or set the message.detail property after initialization:

// getter
var detail = myMessage.getProperty("message.detail");

// setter
myMessage.setProperty("message.detail", "Some 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
Examples

Initialize the element with message.icon attribute:

<oj-message message.icon="images/emailIcon.png" message.summary="Some summary"></oj-messages>

Get or set the icon property after initialization:

// getter
var icon = myMessage.getPropoerty("message.icon");

// setter
myMessage.setProperty("message.icon", "images/emailIcon.png");

message.severity :string

Specifies the severity of message.

Supported Values:
Name Type Description
"confirmation" string confirmation message
"error" string error level message
"info" string informational message
"none" string message status level not applicable
"warning" string warning level message
Default Value:
  • "none"
Since:
  • 5.0.0
Names
Item Name
Property message.severity
Examples

Initialize the element with message.severity attribute:

<oj-message message.severity="error" message.summary="Some summary"></oj-message>

Get or set the message.severity property after initialization:

// getter
var severity = myMessage.getProperty("message.severity");

// setter
myMessage.setProperty("message.severity", "error");

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
Examples

Initialize the element with message.sound attribute:

<!-- Use an URL -->
<oj-message message.sound="resources/audio/newEmail.wav" message.summary="Some summary"></oj-message>

<!-- Use defaults -->
<oj-message message.sound="defaults" message.summary="Some summary"></oj-message>

<!-- Turn off sound -->
<oj-message message.sound="none" message.summary="Some summary"></oj-message>

Get or set the sound property after initialization:

// getter
var sound = myMessage.getProperty("message.sound");

// setter
myMessage.setProperty("message.sound", "resources/audio/newEmail.wav");

message.summary :string

Specifies summary text for the message.

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

Initialize the element with message.summary attribute:

<oj-message message.summary="Some summary"></oj-message>

Get or set the message.summary property after initialization:

// getter
var summary = myMessage.getProperty("message.summary");

// setter
myMessage.setProperty("message.summary", "Some 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
Examples

Initialize the element with message.timestamp attribute:

<oj-message message.summary="Some summary" message.timestamp="2018-03-09T13:10:47+14:00"></oj-message>

Get or set the message.timestamp property after initialization:

// getter
var timestamp = myMessage.getProperty("message.timestamp");

// setter
myMessage.setProperty("message.timestamp", "2018-03-09T13:10:47+14:00");

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
Examples

Initialize the element, overriding some translated resources and leaving the others intact:

<!-- Using dot notation -->
<oj-some-element translations.some-key='Some value' translations.some-other-key='Some other value'></oj-some-element>

<!-- Using JSON notation -->
<oj-some-element translations='{"someKey":"Some value", "someOtherKey":"Some other value"}'></oj-some-element>

Get or set the translations property after initialization:

// Get one
var value = myComponent.getProperty("translations.someKey");

// Set one, leaving the others intact. Always use the setProperty API for
// subproperties rather than setting a subproperty directly.
myComponent.setProperty('translations.someKey', 'some value');

// Get all
var values = myComponent.translations;

// Set all.  Must list every resource key, as those not listed are lost.
myComponent.translations = {
    someKey: 'some value',
    someOtherKey: 'some other value'
};

(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

ojAnimateEnd

Triggered when the default animation is about to end for the open or close actions of the message. The default animation can be cancelled by calling event.preventDefault.
Properties:

All of the event payloads listed below can be found under event.detail.

Name Type Argument Description
element Element <not nullable>
target of animation
action "open" | "close" The action that is ending the animation. The number of actions can vary from component to component. Suggested values are:
  • "open" - when a message is opened
  • "close" - when a message is closed
Since:
  • 5.0.0
Examples

Bind an event listener to the onOjAnimateEnd property to listen for the "close" ending animation:

myMessage.onOjAnimateEnd = function(event) {
  // verify that the component firing the event is a component of interest and action is close
  if (event.detail.action == "close") {}
};

The default open and close animations are controlled via the theme (SCSS) :

// Applies for both 'inline' and 'overlay' messages
$messageGeneralOverlayOpenAnimation: (effect: "zoomIn", fade: true)  !default;
$messageGeneralOverlayCloseAnimation: (effect: "zoomOut", fade: true)  !default;
// Applies for 'notification' messages
$messageNotificationOverlayOpenAnimation: (effect: "zoomIn", fade: true)  !default;
$messageNotificationOverlayCloseAnimation: (effect: "zoomOut", fade: true)  !default;

Specify an ojAnimateEnd listener via the DOM attribute:

<oj-message on-oj-animate-end='[[listener]]'></oj-message>

Specify an ojAnimateEnd listener via the JavaScript property:

myMessage.onOjAnimateEnd = listener;

Add an ojAnimateEnd listener via the addEventListener API:

myMessage.addEventListener('ojAnimateEnd', listener);

ojAnimateStart

Triggered when the default animation is about to start for the open or close actions of the message . The default animation can be cancelled by calling event.preventDefault.

In order to override open animation, the ojAnimateStart event listener needs to be registered before the component is created. This means that onOjAnimateStart cannot be used to register listener for 'open' action because it doesn't exist until the component is upgraded or created at which time it is open. For the 'open' action, use the addEventListener method on the associated oj-message elements or on-oj-animate-start attribute to register a listener instead.

Properties:

All of the event payloads listed below can be found under event.detail.

Name Type Argument Description
element Element <not nullable>
target of animation
action "open" | "close" The action that is starting the animation. Suggested values are:
  • "open" - when a message is opened
  • "close" - when a message is closed
endCallback function():void <not nullable>
If the event listener calls event.preventDefault to cancel the default animation, it must call the endCallback function when it finishes its own animation handling and any custom animation has ended.
Since:
  • 5.0.0
Examples

Bind an event listener to the onOjAnimateStart property to override the default "close" animation:

myMessage.onOjAnimateStart = function(event) {
  // verify that the component firing the event is a component of interest and action is close
  if (event.detail.action == "close") {
    event.preventDefault();
    oj.AnimationUtils.slideOut(event.detail.element, {"persist":  "all"}).then(event.detail.endCallback);
  }
};

The default open and close animations are controlled via the theme (SCSS) :

// Applies for both 'inline' and 'overlay' messages
$messageGeneralOverlayOpenAnimation: ((effect: "zoomIn"), "fadeIn")  !default;
$messageGeneralOverlayCloseAnimation: ((effect: "zoomOut", persist: "all"), "fadeOut")  !default;
// Applies for 'notification' messages
$messageNotificationOverlayOpenAnimation: ((effect: "zoomIn"), "fadeIn")  !default;
$messageNotificationOverlayCloseAnimation: ((effect: "zoomOut", persist: "all"), "fadeOut")  !default;

Specify an ojAnimateStart listener via the DOM attribute:

<oj-message on-oj-animate-start='[[listener]]'></oj-message>

Specify an ojAnimateStart listener via the JavaScript property:

myMessage.onOjAnimateStart = listener;

Add an ojAnimateStart listener via the addEventListener API:

myMessage.addEventListener('ojAnimateStart', listener);

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.

Name Type Description
message Object instance of type oj.ojMessage#message corresponding to the message that was closed
Since:
  • 5.0.0
Examples

Specify an ojClose listener via the DOM attribute:

<oj-message on-oj-close='[[listener]]'></oj-message>

Specify an ojClose listener via the JavaScript property:

myMessage.onOjClose = listener;

Add an ojClose listener via the addEventListener API:

myMessage.addEventListener('ojClose', listener);

Methods

close() → {void}

Closes the message.
Since:
  • 5.0.0
Fires:
  • oj.ojMessage#event:ojAnimationStart
  • oj.ojMessage#event:ojAnimationEnd
  • oj.ojMessage#event:ojClose
Returns:
Type
void
Example

Invoke the close method:

myMessage.close();

getProperty(property) → {*}

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
*
Example

Get a single subproperty of a complex property:

var subpropValue = myComponent.getProperty('complexProperty.subProperty1.subProperty2');

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
Example

Set a batch of properties:

myComponent.setProperties({"prop1": "value1", "prop2.subprop": "value2", "prop3": "value3"});

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 * The new value to set the property to.
Since:
  • 5.0.0
Returns:
Type
void
Example

Set a single subproperty of a complex property:

myComponent.setProperty('complexProperty.subProperty1.subProperty2', "someValue");

Type Definitions

Message

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