ACPaaS UI JS Notification Store

The @acpaas-ui/js-notification-store package provides a singleton store to save and easily access notifications throughout your app. You can load up a message map and trigger notifications by handle. On top of that, you can set targets to hold your notifications (e.g. popups, statusbar, forms). Notifications are returned as BehaviorSubjects, allowing you to subscribe to changes.

Installation

NPM

npm install @acpaas-ui/js-notification-store --save

Yarn

yarn add @acpaas-ui/js-notification-store

Import

// ES2015
import { NotificationStore } from '@acpaas-ui/js-notification-store';

const store = new NotificationStore({
    404: 'not found'
});

store.triggerNotification('404', 'statusbar');

Usage

Loading messages

To load a message map simply provide it in the constructor:

import NotificationStore from 'aui-notification-store';

const store = new NotificationStore({
    404: 'not found'
});

If the allowOverrides option is set to true:

NotificationStore.allowOverrides = true;

you can overwrite the messages with each new instance:

const store2 = new NotificationStore({
    404: 'not here'
});

or, you can call the loadMessages method on the instance:

store.loadMessages({
    404: 'not here'
});

In either case, you need to set the allowOverrides option to true or the existing messages will be preserved.

Triggering notifications

To trigger a notification, you call the triggerNotification method on your store instance. Provide a handle, a (optional) target and some (also optional) extra options:

const store = new NotificationStore({
    404: 'not found'
});

store.triggerNotification('404', 'statusbar', { timer: 1000 });

Clearing notifications

You can clear a notification by calling the clearNotification method on the store:

const notifications = store.getNotifications('statusbar');
const notificationToClear = notifications.find(notification => notification.handle === 'clearme');

store.clearNotification(notificationToClear);

Subscribing to notifications

Each instance has a notifications property, which holds all current notifications as a BehaviorSubject which you can subscribe to:

store.notifications.subscribe(newNotifications => {
    // do something
});

or fetch the current value from (which is an object with a Map of the notifications for each target:

const notifications = store.notifications.getValue();

Available methods and properties

Notification Class

Static properties

• defaultOptions (object): returns a plain object with the default options
• availableTypes (object): getter for the available notification types

Static methods

• parseOptions(options): check the provided options against the default options

Instance properties

• handle (string): the unique handle for the notification message
• target (string): the target to store the notification with
• message (string): the message to be shown when triggering the notification
• type (string): the type of notification (N, I, E, W, S)
• timer (number): the lifespan of the notification once it is shown (in ms)
• scope (string): the app scope the notification should be visible in

NotificationStore Class

Static properties

• allowOverrides (boolean): get/set for the allowOverrides option
• defaultHandle (string): get/set for the default handle to fall back to when triggering a notification
• defaultTarget (string): get/set for the default target to fall back to when triggering a notification
• defaultMessage (string): get/set for the default message to fall back to when triggering a notification
• defaultTimer (number): get/set for the default timer to fall back to when triggering a notification
• defaultScope (string): get/set for the default scope to fall back to when triggering a notification
• messages (object): get/set for the available messages
• options (object): get/set for the currently selected options
• subjects (Map): getter for the current subjects

Static methods

• subscriber(store): add a new BehaviorSubject for a store (internal function)
• getFlatTarget(target): get the notifications as a flat array for a target (internal function)
• getFlatNotifications(target): get the notifications (for a target if provided) as a flat object of target arrays (internal function)
• deleteNotification(notification): delete a notification (internal function)
• updateSubjects(): trigger an update to all subjects (internal function)
• resetStore(): clear all messages and notifications and reset all options

Instance properties

• notifications (BehaviorSubject): a BehaviorSubject that holds all current notifications

Instance methods

• getMessages: get the stored messages
• getMessage(handle): get a message by its handle
• loadMessages(messages): load a new set of messages (takes the allowOverrides option into account)
• triggerNotification(handle, target, options): trigger a new notification by handle, target and provide some extra optional options
• loadNotification(notification): load a new notification, needs a Notification instance
• getNotifications(target): return a flat object holding all notifications or the notifications for the provided target
• clearNotification(notification): clear a notification, needs a Notification instance
• clearTarget(target): clear all notifications for a target, target is required