Union of options objects of all components that can be added to a notification, includes both buttons and primary controls.
Application-defined context data that can be attached to buttons on notifications.
A field in a form.
A fully-hydrated form of NotificationOptions.
After creating a notification, the service will return an object of this type. This will be the given options object, with any unspecified fields filled-in with default values.
This object should be treated as immutable. Modifying its state will not have any effect on the notification or the state of the service.
Data type used to represent the action result returned back to applications when an action is raised. Applications
capture these responses by adding a notification-action listener. The contents of this type are entirely
application-defined, the only requirement is that the item is serializable by JSON.stringify.
Since this type is entirely application-specific, the type is used in these definitions. However, there is an
optional generic argument here, which can be used if an application were to define its own conventions for the shape
of this field (which is recommended). To make use of this, define a notification-action handler that includes the
application-defined type as a template argument. This type is then propogated up to NotificationActionEvent.
The example below demonstrates this, using the same use-case as at the top of this page.
interface MyAction = SnoozeAction | DetailsAction;
interface SnoozeAction {
task: 'schedule-reminder';
intervalMs: number;
}
interface DetailsAction {
task: 'view-calendar-event';
target: 'self'|'popup';
}
addEventListener('notification-action', (event: NotificationActionEvent<MyAction>)) => {
if (event.result.task === 'schedule-reminder') {
// 'event.result' will now be strongly-typed as an instance of SnoozeAction
scheduleReminder(notification.customData.eventId, Date.now() + result.intervalMs);
}
// Etc...
});
An ordered array of fields representing a form. When the form is displayed to the user the fields will appear in the same order they are in the array.
The options you pass to the create function to generate a notification.
Union of all possible notification sources.
Platform object to pass to registerPlatform function.
import { registerPlatform, NotificationsPlatform } from '@openfin/workspace/notifications';
const platform: NotificationsPlatform = {
id: 'my-notifications-platform',
title: 'My Notifications Platform',
icon: 'https://link.to/my-notifications-platform.ico'
}
await registerPlatform(platform);
Number field input widget.
Not yet implemented
Union of the options objects of all "primary control" components supported by the service.
String field input widget.
The options to build your custom template composition layout.
All available widgets.
Event fired when an action is raised for a notification due to a specified trigger. It is important to note that applications will only receive these events if they indicate to the service that they want to receive these events. See {@link Actions} for a full example of how actions are defined, and how an application can listen to and handle them.
This can be fired due to interaction with notification buttons or the notification itself, the notification being
closed (either by user interaction or by API call), or by the notification expiring. Later versions of the service
will add additional control types that may raise actions from user interaction. All actions, for all control types,
will be returned to the application via the same notification-action event type.
The event object will contain the application-defined metadata that allowed this action to be raised, and details on what triggered this action and which control the user interacted with.
Unlike other event types, notification-action events will be buffered by the service until the application has
added a listener for this event type, at which point it will receive all buffered notification-action events. The
service will also attempt to restart the application if it is not running when the event is fired.
This type includes a generic type argument, should applications wish to define their own interface for action results. See NotificationActionResult for details.
The control whose interaction resulted in this action being raised. Will only be present when {@link trigger} is ActionTrigger.CONTROL.
Future versions of the service will add additional controls beyond buttons, and interactions with these new
control types will also come through this one event type. For best forward-compatibility, applications should
always check the type property of this control, and not assume that the type will always be 'button'.
This field is marked optional as future versions of the service will also include alternate methods of raising
notification-action events that do not originate from a button or other control.
When present, the object here will always be strictly equal to one of the control definitions within
notification. This means indexOf checks and other equality checks can be performed on this field if
required, such as:
function onNotificationAction(event: NotificationActionEvent): void {
if (event.control && event.control.type === 'button') {
const butttonIndex = event.notification.buttons.indexOf(event.control);
// Handle button click
// . . .
}
}
The notification that created this action
Application-defined metadata that this event is passing back to the application.
A notification-action event is only fired for a given trigger if the
notification options included an action result for that trigger.
See the comment on the NotificationActionEvent type for an example of buttons that do and don't raise actions.
This property allows the application handling the action to identify where this notification originated.
Indicates what triggered this action.
Note that the programmatic trigger is not yet implemented.
Event fired whenever the notification has been closed.
This event is fired regardless of how the notification was closed - i.e.: via a call to clear/clearAll, the
notification expiring, or by a user clicking either the notification itself, the notification's close button, or
a button on the notification.
The notification that has just been closed.
This object will match what is returned from the create call when the notification was first created.
Event fired whenever a new notification has been created.
The notification that has just been created.
This object will match what is returned from the create call.
Event fired whenever notification toast has been dismissed. This could be either by pressing notification dismiss - button or
by clicking notification body if BODY_CLICK action has been set to "dismiss_event".
Event fired whenever the total number of notifications from all sources changes.
Number of notifications in the Center.
Data type of a fields. e.g. string, number
The StringWidgetType is how you display a text string.
The Notification Client library's version in semver format.
This is the version which you are currently using.
Clears a specific notification from the Notification Center.
Returns true if the notification was successfully cleared. Returns false if the notification was not cleared, without errors.
import {clear} from 'openfin-notifications';
clear('uniqueNotificationId');
ID of the notification to clear.
Clears all Notifications which were created by the calling application, including child windows.
Returns the number of successfully cleared Notifications.
import {clearAll} from 'openfin-notifications';
clearAll();
Creates a new notification.
The notification will appear in the Notification Center and as a toast if the Center is not visible.
If a notification is created with an id of an already existing notification, the existing notification will be recreated with the new content.
import {create} from 'openfin-notifications';
create({
id: 'uniqueNotificationId',
title: 'Notification Title',
body: 'Text to display within the notification body',
category: 'Sample Notifications',
icon: 'https://openfin.co/favicon.ico'
});
Notification configuration options.
Deregisters notifications platform. Throws if you run version of notifications-service which doesn't support platforms.
id of the platform to deregister
Retrieves all Notifications which were created by the calling application, including child windows.
import {getAll} from 'openfin-notifications'
getAll().then((notifications: Notification[]) => {
console.log(`Service has ${notifications.length} notifications for this app:`, notifications);
});
There is deliberately no mechanism provided for fetching notifications that were created by a different application.
Get the total count of notifications from all applications.
import {getNotificationsCount} from 'openfin-notifications';
getNotificationsCount();
Registers notifications platform. Throws if workspace platform is not initialized or if you run version of notifications-service which doesn't support platforms.
NotificationsPlatform object
Toggles the visibility of the Notification Center.
import {toggleNotificationCenter} from 'openfin-notifications';
toggleNotificationCenter();
Updates an existing notification. Requires id of original Notification and one of:
The updated Notification will then show in Notification Centre and in the Toast stack if not expired.
Example:
import {update} from 'openfin-notifications';
update({
id: uniqueNotificationId,
body: 'i am an update! - ' + Date.now().toString(),
template: 'markdown',
});
Generated using TypeDoc
Denotes a field as being an action. Defining this field (with a non-
undefinedvalue) will result in actions being raised and sent back to the source application when the corresponding event happens.For example, providing a value for the
onClickfield of ButtonOptions will result in anotification-actionevent being fired when that button is clicked.In the current version of the service, the
NotificationActionResults returned back to an application are static and must bedefined at the point where the notification is created. Later versions of the service will allow some limited programmatic creation of these results, for use in situations where static result data isn't sufficient.The generic parameters of this type are for future expansion. Future versions of the service will allow for more control over the handling of actions.