Creating a basic notification for Notification Center only takes a few lines of code. The following example show how to construct a basic notification using the title, body, and category properties. To create a notification, call the create() method with a few properties (title, body, category) in your main.js file.

create({
    title: '3 weeks to go until #FinJSatHome',
    body: 'Just three weeks left until #FinJSatHome! Join us to hear how web technologies are causing a revolution in the capital markets...',
    category: 'Event',
    buttons: [
        {
            title: 'Sign Up Now',
            onClick: {
                window.open("https://www.finjs.com/", "_blank")}
            }
        }
    ]
});

Sample Notification

Parts of a notification

Properties

When the properties listed above (title, body, and category) are defined, the notification npm library constructs a notification. These properties, called NotificationOptions, define the content and configure actions for a notification. Some of the NotificationOptions properties are discussed here; for a full list of available properties, refer to NotificationOptions in the API reference.

title

This is the text displayed directly under the notification header in heading style.

body

• This is the main notification content displayed below the main notification title. The body property may contain basic markdown syntax and images (.ico files). A more in-depth explanation of the body property may be found in the body property of the notification API docs.

📘

Note

Links and code blocks are not supported in the body property.

expires

Notifications are set to persist in the Notifications Center app by default. However, a notification can be configured to expire by adding the expires property as a NotificationOption as shown below.

create({
    ...
    expires: date;
});

sticky

In addition to a notification card in the Notifications Center app, a notification also produces a pop-up "toast" on the desktop. In contrast to cards, toasts are transitory unless you use the sticky property with the sticky value (vs. the default value transient) to make them persist until the user dismisses them.

create({
    ...
    sticky: 'sticky';
});

📘

Use with care

Avoid overwhelming the user with too many persistent toasts. Use this option only for really important notifications.

indicator

A notificationIndicator adds a colored banner at the top of the notification card or toast. An indicator consists of a text string summarizing the condition and an indicatorType, which can be one of the following:

• FAILURE
  • Indicates a failure has occurred, usually from an action the user has taken
  • Shown as a red banner
• WARNING
  • Warns a user that a significant event is occurring, for example, that they have a limited time to buy
  • Shown as an amber banner
• SUCCESS
  • Tells the user that an item has been successful
  • Shown as a green banner

📘

Note

The maximum size of NotificationIndicator.text is 32 characters.

category

Categories describe the context of a notification. This allows you as an application provider to control different types of notifications that are raised by your application based on context. For example, if you create calendar notifications you can categorize them for the end-user. Categories like Upcoming Events for notifications when an event is about to start and Event Start for notifications for when an event starts are helpful for the user, as they can distinguish what category the notification belongs to.

To set a category, add the category NotificationOption to the notification and set the value to a string. Once implemented, the string associated with the category is displayed in the Notification Center app preferences, so that the user can choose whether they want to receive notifications for this category.

Buttons

Notifications allow you to construct and control buttons within a notification. Configuration of ButtonOptions allows for an icon and button text to be added to a button, as well as onClick properties.
To create a button, provide a buttons property as part of the notification definition.

create({
    ...
    buttons: [
        {
            title: 'Snooze for 5 minutes',
            iconUrl: 'https://www.example.com/timer.png',
            onClick: {
                task: 'schedule-reminder',
                intervalMs: 5 * 60 * 1000
            }
        }
     ]
});

Actions

Actions are an integral property in creating a Notification system. Actions are how notifications send data back to their OpenFin host application. Notifications have a number of ways in which actions can be raised, typically through user interactions (for example, clicking a button). As an Application Provider, you decide if you want to implement ways to be informed of these raised interactions and their corresponding events.

Below is an example of a basic application configured with actions. This example constructs a notification, configures a button, and demonstrates configuring the application to listen for a notification action that triggers an event. For more details on how to configure NotificationActionsEvent, refer to Actions.

import {addEventListener, create} from 'openfin-notifications';

// Create a notification with two buttons
create({
    title: 'Reminder',
    body: 'Event "Weekly Meeting" is starting soon...',
    category: 'Upcoming Events',

    // Use the 'customData' field to store metadata about the event
    customData: {
        eventId: '12345'
    },

    // register an 'onSelect' event to capture the user click event
    onSelect: {
        task: 'view-calendar-event',
        target: 'popup'
    },

    buttons: [
        // Button schedules another reminder for 5 minutes later 
        {
            title: 'Snooze for 5 minutes',
            iconUrl: 'https://www.example.com/timer.png',
            onClick: {
                task: 'schedule-reminder',
                intervalMs: 5 * 60 * 1000
            }
        },

        // Button closes notification and doesn't reprompt the user
        {
            title: 'Dismiss',
            iconUrl: 'https://www.example.com/cancel.png'
        }
    ]
});

// Create a listener that is called for each action
// Note: This handler is used for ALL actions, from ALL
// notifications that are created by this application.
addEventListener('notification-action', (event: NotificationActionEvent) => {
    const {
        result,
        notification
    } = event;

    if (result['task'] === 'view-calendar-event') {
        // Open a window with full details of the associated event
        openEventDetails(notification.customData.eventId, result['target']);
    } else if (result['task'] === 'schedule-reminder') {
        // Schedule a new notification
        scheduleReminder(
            notification.customData.eventId,
            Date.now() + result['intervalMs']
        );
    } // Etc...
});

actionEvent

A event that is fired when a user interacts with a notification UI element is called a NotificationActionEvent.

📘

Note

An application receives these events only if it has indicated that it wants to receive them.

The best way for an application to set a NotificationActionEvent is to create a listener for the initial notification-action done by the user. Creating a listener for a notification action allows the application to listen for new events and fire the consumed NotificationActionEvent, making a streamlined chain of call-and-response commands for notifications.

To create a NotificationActionEvent, add a listener to a notification-action as per the example below. This listens for the user to complete this action and complete the set NotificationActionEvent.

// Create a listener that is called for each action
// Note: This handler is used for ALL actions, from 
// ALL notifications that are created by this application.
addEventListener('notification-action', (event: NotificationActionEvent) => {
    const {result, notification} = event;

    if (result['task'] === 'your-apps-event') {
        // Open a window with full details of the associated event
        openEventDetails(notification.customData.eventId, result['target']);
    } else if (result['task'] === 'your-apps-reminder') {
        // Schedule a new notification
        scheduleReminder(notification.customData.eventId, Date.now() + result['intervalMs']);
    } // Etc...
});

Triggers

Notifications also permit triggers that can raise actions. Each action raised results in a NotificationActionEvent. For example, if you configure the select trigger with a NotificationActionEvent like the one above, when a user clicks on the body of the notification and none of the clicks hit a control or the close button, the set 'select' action is triggered.

App relaunch

Notifications allow configuring buttons that relaunch an application if it’s closed. For example, if an application is closed and the user views a notification from it, the user can click a button in the notification to relaunch the associated application.

To permit relaunch of an application

1. Create a button (as shown in the code above)
2. Configure it with the onSelect property and a corresponding action as outlined in the NotificationsActionEvent section.