Options
All
  • Public
  • Public/Protected
  • All
Menu

Module notifications

Index

Namespaces

Enumerations

Interfaces

Type Aliases

Events

Variables

Functions

Type Aliases

ActionDeclaration<T, E>: NotificationActionResult

Denotes a field as being an action. Defining this field (with a non-undefined value) 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 onClick field of ButtonOptions will result in a notification-action event 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.

Type Parameters

  • T extends never

  • E extends never

CheckboxWidgetSpec: BaseWidgetSpec<typeof WidgetType["Checkbox"]>
ControlOptions: PrimaryControlOptions | WithExplicitType<ButtonOptions>

Union of options objects of all components that can be added to a notification, includes both buttons and primary controls.

CustomData: Record<string, any>

Application-defined context data that can be attached to buttons on notifications.

CustomTemplateData: Record<string, string | ListPairs>

A field in a form.

ImageTemplateFragment: PresentationTemplateFragment<"image">
ListPairs: [string, string][]
ListTemplateFragment: PresentationTemplateFragment<"list">
Notification<T>: Readonly<Required<DistributiveOmit<T, "buttons">> & { buttons: ReadonlyArray<Required<ButtonOptions>> }>

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.

Type Parameters

NotificationActionResult<T>: T

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...
});

Type Parameters

NotificationFormData: ReadonlyArray<FormField>

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.

NotificationSource: NotificationSourceDesktop

Union of all possible notification sources.

NotificationsPlatform: Omit<NotificationsPlatformInternal, "theme">

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);
NumberWidget: NumberWidgetSpec

Number field input widget.

PrimaryControlOptions: never

Not yet implemented

Union of the options objects of all "primary control" components supported by the service.

SectionAlignment: "left" | "center" | "right"
StringWidget: TextWidgetSpec

String field input widget.

The options to build your custom template composition layout.

TextTemplateFragment: PresentationTemplateFragment<"text">
ToggleWidgetSpec: BaseWidgetSpec<typeof WidgetType["Toggle"]>
UpdatableNotification<T>: Readonly<DistributiveOmit<T, "buttons"> & { buttons?: ReadonlyArray<Required<ButtonOptions>> }>

Type Parameters

All available widgets.

Events

NotificationActionEvent<T>

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.

Type Parameters

control?: Readonly<Required<WithExplicitType<ButtonOptions>>>

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
// . . .
}
}
notification: Readonly<Readonly<Required<Omit<TemplateMarkdown, "buttons">> & { buttons: readonly Required<ButtonOptions>[] } & Required<Omit<TemplateList, "buttons">> & { buttons: readonly Required<ButtonOptions>[] } & Required<Omit<TemplateCustom, "buttons">> & { buttons: readonly Required<ButtonOptions>[] }>>

The notification that created this action

result: T

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.

trigger: ActionTrigger

Indicates what triggered this action.

Note that the programmatic trigger is not yet implemented.

type: "notification-action"
NotificationClosedEvent

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.

notification: Readonly<Required<Omit<TemplateMarkdown, "buttons">> & { buttons: readonly Required<ButtonOptions>[] } & Required<Omit<TemplateList, "buttons">> & { buttons: readonly Required<ButtonOptions>[] } & Required<Omit<TemplateCustom, "buttons">> & { buttons: readonly Required<ButtonOptions>[] }>

The notification that has just been closed.

This object will match what is returned from the create call when the notification was first created.

type: "notification-closed"
NotificationCreatedEvent

Event fired whenever a new notification has been created.

notification: Readonly<Required<Omit<TemplateMarkdown, "buttons">> & { buttons: readonly Required<ButtonOptions>[] } & Required<Omit<TemplateList, "buttons">> & { buttons: readonly Required<ButtonOptions>[] } & Required<Omit<TemplateCustom, "buttons">> & { buttons: readonly Required<ButtonOptions>[] }>

The notification that has just been created.

This object will match what is returned from the create call.

type: "notification-created"
NotificationsCountChanged

Event fired whenever the total number of notifications from all sources changes.

count: number

Number of notifications in the Center.

type: "notifications-count-changed"

Variables

BooleanWidgetType: { Checkbox: "Checkbox"; Toggle: "Toggle" }

Type declaration

  • Readonly Checkbox: "Checkbox"
  • Readonly Toggle: "Toggle"
ContainerTemplateFragmentNames: { container: "container" }

Type declaration

  • Readonly container: "container"
FieldType: { boolean: "boolean"; number: "number"; string: "string" }

Data type of a fields. e.g. string, number

Type declaration

  • Readonly boolean: "boolean"
  • Readonly number: "number"
  • Readonly string: "string"
NumberWidgetType: { Number: "Number" }

Type declaration

  • Readonly Number: "Number"
PresentationTemplateFragmentNames: { image: "image"; list: "list"; text: "text" }

Type declaration

  • Readonly image: "image"
  • Readonly list: "list"
  • Readonly text: "text"
StringWidgetType: { Text: "Text" }

The StringWidgetType is how you display a text string.

Type declaration

  • Readonly Text: "Text"
TemplateFragmentNames: { container: "container"; image: "image"; list: "list"; text: "text" }

Type declaration

  • Readonly container: "container"
  • Readonly image: "image"
  • Readonly list: "list"
  • Readonly text: "text"
TemplateNames: { custom: "custom"; list: "list"; markdown: "markdown" }

Type declaration

  • Readonly custom: "custom"
  • Readonly list: "list"
  • Readonly markdown: "markdown"
VERSION: string

The Notification Client library's version in semver format.

This is the version which you are currently using.

WidgetType: { Checkbox: "Checkbox"; Number: "Number"; Text: "Text"; Toggle: "Toggle" }

Type declaration

  • Readonly Checkbox: "Checkbox"
  • Readonly Number: "Number"
  • Readonly Text: "Text"
  • Readonly Toggle: "Toggle"

Functions

  • clear(id: string): Promise<boolean>
  • 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');

    Parameters

    • id: string

      ID of the notification to clear.

    Returns Promise<boolean>

  • clearAll(): Promise<number>
  • 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();

    Returns Promise<number>

  • 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'
    });

    Type Parameters

    Parameters

    • options: T

      Notification configuration options.

    Returns Promise<Notification<T>>

  • deregister(platformId: string): Promise<void>
  • Deregisters notifications platform. Throws if you run version of notifications-service which doesn't support platforms.

    Parameters

    • platformId: string

      id of the platform to deregister

    Returns Promise<void>

  • 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.

    Returns Promise<Notification[]>

  • getNotificationsCount(): Promise<number>
  • Get the total count of notifications from all applications.

    import {getNotificationsCount} from 'openfin-notifications';

    getNotificationsCount();

    Returns Promise<number>

  • Registers notifications platform. Throws if workspace platform is not initialized or if you run version of notifications-service which doesn't support platforms.

    Parameters

    Returns Promise<void>

  • toggleNotificationCenter(): Promise<void>
  • Toggles the visibility of the Notification Center.

    import {toggleNotificationCenter} from 'openfin-notifications';

    toggleNotificationCenter();

    Returns Promise<void>

  • Updates an existing notification. Requires id of original Notification and one of:

    • buttons
    • customData
    • Template

    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',
    });

    Type Parameters

    Parameters

    • options: T

    Returns Promise<Notification>

Generated using TypeDoc