Element: <oj-c-message-toast>

CORE PACK

Oracle® JavaScript Extension Toolkit (JET)
17.1.0
G12196-01

Since:
  • 14.0.0
Module:
  • message-toast

Note: This component supersedes the following component: <oj-messages>. Migration info available at preceding link.

QuickNav

Slots

Attributes

Events

Methods

Type Definitions

Other Topics


JET Message Toast

Description:

Message toasts are short, non-critical, auto-dismissible messages that communicate non-disruptive contextual messages.

Toast messages are used to:

  • Communicate messages that are relevant in the moment like the acknowledgement of an action.
  • Allow user to take actions related to an event or process, such as: retry, undo, view.

Syntax

Message Toast can be created with the following markup.


<oj-c-message-toast data="[[messages]]">
</oj-c-message-toast>

The Message Toast 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-toast data="[[messages]]" on-oj-close="[[handleClose]]">
</oj-c-message-toast>

Accessibility

The MessageToastItem["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 CMessageToastElement<K extends string | number,D extends oj-c.MessageToast.MessageToastItem>

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 MessageToastItem type.
Typescript Import Format
//To typecheck the element APIs, import as below.
import { CMessageToastElement } from "oj-c/message-toast";

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

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.MessageToastTemplateContext (Dynamic)

Structure of template context used for dynamic templates

Note: For additional information see detail-template-value, icon-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 Toast component. This data is used for rendering each toast 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.

When specifying a DataProvider for the data attribute, you need to provide the keyAttributes for the DataProvider. The oj-c-message-toast 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.MessageToast.MessageToastTemplateValueParameters<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 MessageToastTemplateValueParameters 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.

Note: For additional information see DynamicSlots.MessageToastTemplateContext.

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

icon-template-value :string|(parameters: oj-c.MessageToast.MessageToastTemplateValueParameters<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 icon content. When a template name is provided as a value for this property, the corresponding template will be used for rendering the icon 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 MessageToastTemplateValueParameters and return a key to a template for rendering the corresponding message's icon 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 icon content using the icon property of the corresponding message. If an application specifies both icon and a valid icon-template-value, the icon-template-value will take precedence and the corresponding template will be used for rendering the icon content.

Note: For additional information see DynamicSlots.MessageToastTemplateContext.

Names
Item Name
Property iconTemplateValue
Property change event iconTemplateValueChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-icon-template-value-changed

offset :number|{ horizontal?: number; vertical?: number; }

Defines an offset (in pixels) in the placement. Value can be supplied as a number or an object with horizontal and vertical values.
Default Value:
  • 0
Names
Item Name
Property offset
Property change event offsetChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-offset-changed

position :"top"|"bottom"|"top-start"|"top-end"|"bottom-end"|"bottom-start"|"top-left"|"top-right"|"bottom-left"|"bottom-right"

Defines the fixed position where the messages will be positioned on the screen. - top-start resolves to top-left in LTR (top-right in RTL) - top-end resolves to top-right in LTR (top-left in RTL) - bottom-start resolves to bottom-left in LTR (bottom-right in RTL) - bottom-end resolves to bottom-right in LTR (bottom-left in RTL)
Default Value:
  • "bottom"
Names
Item Name
Property position
Property change event positionChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-position-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

MessageToastItem

An object representing a single message in MessageToast component.
Properties:
Name Type Argument Description
autoTimeout (number|string) <optional>
 Defines the time after which the message is to be closed automatically on - default of 5s off - no auto timeout, manually dismissed number - seconds in milliseconds format
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

MessageToastTemplateValueParameters<K extends string | number,D extends oj-c.MessageToast.MessageToastItem>

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