Skip to main content

Interactions in a notification

You can configure user interactions in a notification for:

These elements all depend on the Actions module, which lets you respond to events that are generated by any of the following:

  • The action triggers associated with the onClick property of buttons or actionable fragments

  • The onSelect property of the notification body

  • Form validation or submission

How it works​

You provide a NotificationActionResult object -- represented as CustomData -- for the onClick property of a button or actionable fragment, or for the onSelect property of the body of the notification. This generates an event of type notification-action you configure your application to receive.

If you do not specify NotificationActionResult, for example for the case where a button represents a "dismiss" or "cancel" action, a notification-closed event is generated. For a complete list of events, see the API reference for addEventListener. These events are types of the NotificationActionEvent interface .

You configure your application to receive events with the addEventListener function, and define the how the application responds as part of the function.

For forms, the event types are notification-form-submitted and notification-form-values-changed. See the Forms article for details about how to configure a form, its special button properties, and its event listeners.

The following example:

  • Creates a notification that defines the onSelect and buttons.onClick properties with custom data

  • Defines the related addEventListener to respond when the user selects the body of the notification or clicks the actionable button

The following example shows how to construct a notification that includes a button with the onClick property. It also configures the sending application to listen for the associated event.

import {addEventListener, create} from "@openfin/workspace/notifications";

// Create notification to remind and link to an external calendar event
create(
{
  // note that this is a reminder about an external event, not the notification itself
  title: "Reminder",
  body: "Event "Weekly Meeting" is starting soon...",

  // custom data about the notification itself, not the user interaction
  customData: {
    eventId: "12345"
  },

  // register an "onSelect" event for when the user selects the body of the notification
  // sends the user to the external calendar application
  onSelect: {
    task: "view-calendar-event",
    target: "popup"
  },

  buttons: [
    // Button schedules another reminder for 5 minutes later
    // this reminder is sent from the external application, not the notifications app 
    {
      title: "Snooze for 5 minutes",
      iconUrl: "https://www.example.com/timer.png",
      cta: true,
      onClick: 
      // application defined properties and data
      {
        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
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...
});

Table of Contents