Element: <oj-c-message-banner>

CORE PACK

Oracle® JavaScript Extension Toolkit (JET)
17.0.0

F92240-01

Since:
  • 16.0.0
Module:
  • message-banner

Note: This component supersedes the following components: <oj-messages>, <oj-message-banner>. Migration info available at preceding links.

QuickNav

Attributes


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-c-message-banner data="[[messages]]" type="page">
</oj-c-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-c-message-banner data="[[messages]]" type="page" on-oj-close="[[handleClose]]">
</oj-c-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.


Usage

Signature:

interface CMessageBannerElement<K extends string | number,D extends oj-c.MessageBanner.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 { CMessageBannerElement } from "oj-c/message-banner";

//For the transpiled javascript to load the element's module, import as below
import "oj-c/message-banner";

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.

DynamicSlots.MessageBannerTemplateContext (Dynamic)

Structure of template context used for dynamic templates

Note: For additional information see detail-template-value.

Properties of $current:
Name Type Description
data D The data for the current message
key K The key for the current message
metadata ItemMetadata.<K> The metadata for the current message

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-c-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|(parameters: oj-c.MessageBanner.MessageBannerTemplateValueParameters<K, D>) => string | undefined

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 object of type MessageBannerTemplateValueParameters 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 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.

Note: For additional information see DynamicSlots.MessageBannerTemplateContext.

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

sorting :"severity"|"off"

Specifies how to sort the messages from the dataprovider.
Supported Values:
Value Description
off Messages appear in the order they are supplied with no additional sorting.
severity Sort the messages in the decreasing order of severity: error, warning, info, confirmation, and none. Then sort the messages of the same severity in reverse chronological order using the timestamp property.
Default Value:
  • "severity"
Names
Item Name
Property sorting
Property change event sortingChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-sorting-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.
Supported Values:
Value Description
page Renders the messages as edge-to-edge messages with no gap in between them.
section Renders the messages as section messages - with rounded corners, outline and gap between messages.
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 Description
data D The data that was used to render the message.
key K The key for the message.
metadata ItemMetadata.<K> The metadata of the message.

Methods

getProperty(property) : {any}

Retrieves the value of a property or a subproperty.
Parameters:
Name Type Description
property 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 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 corresponding event.
Parameters:
Name Type Description
property The property name to set. Supports dot notation for subproperty access.
value The new value to set the property to.
Returns:
Type
void

Type Definitions

MessageBannerItem

An object representing a single message in MessageBanner component.
Properties:
Name Type Argument Description
closeAffordance "off" | "on" <optional>
Defines whether or not to include the close icon for the message
detail string <optional>
Defines the detail text of the message
severity "none" | "error" | "confirmation" | "info" | "warning" <optional>
Defines the severity of the message
sound 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

MessageBannerTemplateValueParameters<K extends string | number,D extends oj-c.MessageBanner.MessageBannerItem>

Structure of parameters passed on to the templateKey properties.
Properties:
Name Type Description
data D The data for the current message
key K The key for the current message
metadata ItemMetadata.<K> The metadata for the current message