Options
All
  • Public
  • Public/Protected
  • All
Menu

OpenFin Notification Center - v1.5.0

Index

Type aliases

ActionDeclaration

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: never

  • E: never

ControlOptions

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

CustomData: Record<string, any>

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

FormField

A field in a form.

Notification

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

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

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.

NotificationOptions

NotificationOptions: TemplateMarkdown | TemplateList

The options you pass to the create function to generate a notification.

NotificationSource

Union of all possible notification sources.

NumberWidget

NumberWidget: NumberWidgetSpec

Number field input widget.

PrimaryControlOptions

PrimaryControlOptions: never

Not yet implemented

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

StringWidget

StringWidget: TextWidgetSpec

String field input widget.

Widget

All available widgets.

Events

NotificationActionEvent

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

Optional control

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

The control whose interaction resulted in this action being raised. Will only be present when 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

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

The notification that created this action

result

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.

source

Notifications can be created by both desktop applications and as push notifications from a notification feed.

This property allows the application handling the action to identify where this notification originated.

trigger

trigger: ActionTrigger

Indicates what triggered this action.

Note that the programmatic trigger is not yet implemented.

type

type: "notification-action"

NotificationClosedEvent

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

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

type: "notification-closed"

NotificationCreatedEvent

NotificationCreatedEvent:

Event fired whenever a new notification has been created.

notification

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

The notification that has just been created.

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

type

type: "notification-created"

NotificationsCountChanged

NotificationsCountChanged:

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

count

count: number

Number of notifications in the Center.

type

type: "notifications-count-changed"

Variables

Const FieldType

FieldType: { number: "number"; string: "string" } = ...

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

Type declaration

  • number: "number"
  • string: "string"

Const NumberWidgetType

NumberWidgetType: { Number: "Number" } = ...

Type declaration

  • Number: "Number"

Const StringWidgetType

StringWidgetType: { Text: "Text" } = ...

The StringWidgetType is how you display a text string.

Type declaration

  • Text: "Text"

Const TemplateNames

TemplateNames: { list: "list"; markdown: "markdown" } = ...

Type declaration

  • list: "list"
  • markdown: "markdown"

Const VERSION

VERSION: string = ...

The Notification Client library's version in semver format.

This is the version which you are currently using.

Const WidgetType

WidgetType: { Number: "Number"; Text: "Text" } = ...

Type declaration

  • Number: "Number"
  • Text: "Text"

Functions

addEventListener

clear

  • 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

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

create

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

getAll

  • 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

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

    import {getNotificationsCount} from 'openfin-notifications';
    
    getNotificationsCount();
    

    Returns Promise<number>

isSubscribed

  • isSubscribed(feedId: string): Promise<boolean>
  • Checks if the currently logged in user is subscribed to the given feed.

    throws

    If there is no user currently logged in

    throws

    If the given feedId does not map to a known feed

    throws

    If the version of the provider version is insufficient

    since

    0.12.3

    Parameters

    • feedId: string

      The ID of the feed to query

    Returns Promise<boolean>

removeEventListener

requestSubscribe

  • requestSubscribe(feedId: string): Promise<void>
  • Creates a notification prompting the user to subscribe to the given feed.

    throws

    If there is no user currently logged in

    throws

    If the given feedId does not map to a known feed

    throws

    If the version of the provider version is insufficient

    since

    0.12.3

    Parameters

    • feedId: string

      The ID of the feed to query

    Returns Promise<void>

toggleNotificationCenter

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

    import {toggleNotificationCenter} from 'openfin-notifications';
    
    toggleNotificationCenter();
    

    Returns Promise<void>

Generated using TypeDoc