Element: <oj-message-banner>

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

Since:
  • 12.0.0
Module:
  • ojmessagebanner

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

Note: This component is not supported in the following themes: Alta

QuickNav

Attributes

Events

Methods

Type Definitions

Other Topics


JET Message Banner

Description:

Message banners are brief, moderately disruptive, semi-permanent messages that help communicate relevant and useful information in the context of the current page or actions in progress, without blocking the interaction on that page.

Syntax

Message Banner can be created with the following markup.


<oj-message-banner data="[[messages]]" type="page">
</oj-message-banner>

The Message Banner component will show messages based on the data provided keeping it as a single source of truth. Applications should register a listener for the ojClose event to be notified when one performs an action that requires a message to be closed. The application then should use the event payload to identify and remove the corresponding row from the data which would then close the message.


<oj-message-banner data="[[messages]]" type="page" on-oj-close="[[handleClose]]">
</oj-message-banner>

Accessibility

The MessageBannerItem["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 "default" or by providing a 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.

Keyboard End User Information

Target Key Action
Focus within Messages Tab or Shift + Tab Navigate the content of the messages region.
F6 Cycles the focus through all the messages sections on the page starting from the most recent one. Then finally, moves the focus back to the last focused element outside the messages region.
Esc Moves focus back to the last focused element outside the messages region and closes the current message if it is closable.
Enter or Space Activates the currently focused element in the message.
Focus outside Messages F6 Move focus to the first message within the more recently disclosed messages region.

Migration

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

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

detail-template-value

When using a function for the detail-template-value attribute, you now need to return undefined to have the component render the default detail content. Returning null is not supported in the oj-c-message-banner component.

MessageBannerTemplateContext

The template context provided for the template slots will not have the index property in the oj-c-message-banner component. If needed, applications can still use the key property to identify the message being rendered.

Sorting

The oj-c-message-banner sorts the messages by default based on the decreasing order of severity. The messages of the same severity are then sorted in reverse chronological order. Set the sorting attribute to "off" to show the messages in the order that they appear in the data.


Usage

Signature:

interface MessageBannerElement<K extends (string | number),D extends (ojMessageBanner.MessageBannerItem)>

Generic Parameters
ParameterDescription
KType of key of the dataprovider. It can either be a string or a number.
DType of the data from the dataprovider. It must extend the MessageBannerItem type.
Typescript Import Format
//To typecheck the element APIs, import as below.
import { MessageBannerElement } from "ojs/ojmessagebanner";

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

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.


Attributes

data :DataProvider.<K, D>

Data for the Message Banner component. This data is used for rendering each banner message. This is a required attribute. If an application needs to initialize the component with no initial messages, it would need to provide an empty DataProvider. When the application wants to show messages, it can then add new data to the existing DataProvider. See MutableArrayDataProvider for more details.

When specifying a DataProvider for the data attribute, you need to provide the keyAttributes for the DataProvider. The oj-message-banner component expects a single attribute of type string or number as the key of the DataProvider. When the data is updated this key attribute will be used to determine whether a new message is being added or an existing message is being updated. This is required for performing necessary animations. When the application replaces the DataProvider, the component assumes that all the messages are newly added irrespective of their keys and performs animation accordingly.

Names
Item Name
Property data
Property change event dataChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-data-changed

detail-template-value :string | ((itemContext:ojcommontypes.ItemContext<K,D>) => string|null)

Applications can use this property to provide the name of a template or a function that returns the name of a template to use for rendering the detail content. When a template name is provided as a value for this property, the corresponding template will be used for rendering the detail content for all the messages. If applications want to use a different template for different messages, they can provide a function that returns a template name instead. The provided function should accept an ItemContext and return a key to a template for rendering the corresponding message's detail content. The value returned from this function should be a key to one of the dynamic template slots provided. If the returned value is not one of the keys of the provided dynamic template slots, the component will throw an Error. If the function returns null or undefined, the component then will perform default rendering of the detail content using the detail property of the corresponding message. If an application specifies both detail and a valid detail-template-value, the detail-template-value will take precedence and the corresponding template will be used for rendering the detail content.
Names
Item Name
Property detailTemplateValue
Property change event detailTemplateValueChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-detail-template-value-changed

type :"page"|"section"

A Banner message can have a different look and feel. For example, when using page-level messaging the messages need to be rendered from edge to edge without any outline. On the other hand, when they are being used in a section of a page or a dialog, they need to be rendered with an outline. This attribute can be used to specify where the component is being used so that it will render the messages accordingly.
Default Value:
  • 'section'
Names
Item Name
Property type
Property change event typeChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-type-changed

Events

ojClose

Triggered when a user tries to close a message through UI interaction. The application should listen to this event and remove the corresponding message item from the data which would then result in the message being closed. If the application fails to remove the message item from the data, then no change will be done in the UI by the component and the message will stay in the UI opened.
Properties:

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

Name Type Argument Description
data D The data that was used to render the message.
key K The key for the message.
metadata ItemMetadata.<K> <optional>
 The metadata of the message.

Methods

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.
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.
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.
Returns:
Type
void

Type Definitions

MessageBannerItem

Properties:
Name Type Argument Description
closeAffordance "on" | "off" <optional>
 Defines whether or not to include the close icon for the message
detail string <optional>
 Defines the detail text of the message
severity ("error"|"warning"|"confirmation"|"info"|"none") <optional>
 Defines the severity of the message
sound "default" | "none" | string <optional>
 Defines the sound to be played when opening the message
summary string <optional>
 Defines the primary text of the message
timestamp string <optional>
 Defines the timestamp for the message in ISO format