Element: <oj-messages>

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:
  • ojmessages

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.

Attributes

display :string

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#position property 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:
Name Type Description
"general" string messages pertaining to the page or region of the application
"notification" string 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
Examples

Initialize component with display attribute:

<oj-messages display="notification" position="{}"></oj-messages>

Get or set the display property after initialization:

// getter
var display = myMessages.display;

// setter
myMessages.display = "notification";

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

Specifies the array 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.

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
Examples

Initialize component with messages attribute:

<!-- emailNotifications is an array of messages, with each entry being of 'Message' type -->
<oj-messages messages="[[emailNotifications]]"></oj-messages>

Get or set the messages property after initialization:

// getter
var messages = myMessages.messages;

// setter
myMessages.messages = [{"severity": "error", "summary": "Some summary 1", "detail": "Some detail 1"},
                       {"severity": "warning", "summary": "Some summary 2", "detail": "Some detail 2"}];

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.

Default Value:
  • null
Names
Item Name
Property position
Property change event positionChanged
Property change listener attribute (must be of type function) on-position-changed
Examples

Initialize the popup with position attribute specified:

<oj-messages position.my.horizontal="left"
             position.my.vertical="top"
             position.at.horizontal="right"
             position.at.vertical="top">
</oj-messages>;

Get or set the position property, after initialization:

// getter
var position = myMessages.position;

// setter
myMessages.position =
   {"my": {"horizontal": "start", "vertical": "bottom"},
    "at": {"horizontal": "end", "vertical": "top" },
    "offset": {"x": 0, "y":5}};

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

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

position.at.vertical :string

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

position.collision :string

Rule for alternate alignment.
Supported Values:
Name Type Description
"fit" string shift the element away from the edge of the window.
"flip" string 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" string 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" string 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.
Default Value:
  • {"horizontal" : "center", "vertical" : "top"}
Names
Item Name
Property position.my

position.my.horizontal :string

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

position.my.vertical :string

Defines the vertical alignment of the messages overlay.
Supported Values:
Name Type
"bottom" string
"center" string
"top" string
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
Example

Finding the point for an svg element:

var rect = svgDom.getBoundingClientRect();
var position = {of:{x:rect.left + window.pageXOffset, y:rect.top + window.pageYOffset}};

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
Examples

Initialize the component, 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.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.setProperty("translations.someKey" 'some value');

(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(associated) → {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
associated Object message instance of type oj.ojMessage#message
Since:
  • 5.0.0
Returns:
Type
void
Example

Invoke the close method:

myMessages.close(myMessage.message);

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: oj.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
Example

Invoke the closeAll method:

myMessages.closeAll(function (message)
{
  // close all messages of error severity
  return "error" === message.severity;
});

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

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.