North Pittsburgh Meatpackers

    @commercetools-frontend/notifications
    TypeScript icon, indicating that this package has built-in type declarations

    20.10.1 • Public • Published

    @commercetools-frontend/notifications

    Latest release (latest dist-tag) Latest release (next dist-tag) Minified + GZipped size GitHub license

    A general-purpose notification system built on top of redux.

    Install

    $ npm install --save @commercetools-frontend/notifications

    Action Creator

    addNotification(notification, [options])

    Arguments

    1. notification (Object): This notification will get added to the list. See Notification.
    2. [options] (Object): If specified, further customizes the behavior of the notification.
    • [dismissAfter = 0] (Number): dismiss the component after this duration (milliseconds)
    • [onDismiss] (Function): Callback which will get called with the notification's id before it is dismissed.

    The payload must be a Notification object. The id will be added by the middleware automatically.

    Returns

    After dispatching a notification to the middleware a notificationHandle will be returned.

    {
      id: Number,
      dismiss: Function,
    }

    Notification

    {
      id: Number,
    }

    A notification in the state will always have an id which gets added by the middleware automatically, plus any props passed as the payload on creation.

    Action Format

    {
      type: 'ADD_NOTIFICATION',
      payload: Object,
      meta: {
        dismissAfter: Number
      }
    }

    removeNotification(id)

    Arguments

    1. id (Number): This notification will be removed

    Example action

    {
      type: 'REMOVE_NOTIFICATION',
      payload: Number,
    }

    Middleware

    The middleware

    • adds a unique id to every notification
    • handles scheduling removal of notifications specifying dismissAfter
    • returns a notificationHandle for each dispatched notification containing its id and a dismiss function for convenience.

    Integration

    import { createStore, applyMiddleware } from 'redux';
    import { middleware as notificationsMiddleware } from '@commercetools-frontend/notifications';
    import rootReducer from './reducers';
    
    // Note: this API requires redux@>=3.1.0
    const store = createStore(
      rootReducer,
      applyMiddleware(notificationsMiddleware)
    );

    Reducer

    Mount the reducer on your notifications store slice.

    reducer

    Example

    combineReducers({
      notifications: reducer,
      ...more reducers here...
    })

    Action Types

    Although not required for use in the application, these are exported as well.

    • ADD_NOTIFICATION
    • REMOVE_NOTIFICATION

    They can be used for filtering out notification actions in the logger.

    Usage

    With React

    import React from 'react'
    import PropTypes from 'prop-types';
    import { removeNotification } from '@commercetools-frontend/notifications'
    
    // Accepts a notification map function,
    // which returns the component based on the notification.
    //
    // function mapNotificationToComponent (notification) {
    //   const map = {
    //     'success': SuccessNotification,
    //     'intercom': IntercomNotification,
    //   }
    //   return map[notification.kind] || InfoNotification
    // }
    //
    // accept notifications, which should come from connecting to the store
    
    class LeftNavigation extends React.PureComponent {
      static propTypes: {
        notifications: PropTypes.arrayOf(PropTypes.object).isRequired,
        mapNotificationToComponent: PropTypes.func.isRequired,
      };
    
      render () {
        return (
          <div>
            {
              this.props.notifications.map(
                notification => {
                  const Component = this.props.mapNotificationToComponent(notification)
                  const dismiss = () => removeNotification(notification.id)
                  return (
                    <Component
                      key={notification.id}
                      notification={notification}
                      dismiss={dismiss}
                    />
                  )
                }
              )
            }
          </div>
        )
      };
    }

    • The notification system is unaware of the types of notifications you are going to dispatch. It's recommended to call the types of notifications you have kind, to not confuse it with Action Types.
    • The notification system is also unaware of the domain's used in the application. A domain is the part of the application where the notification will be displayed. We currently have: global, page and side
    • addNotification is a low-level function. It's recommended to use it in your own action-creators, and use your own action-creators in your application exclusively calling addNotification behind the scenes.
    • to hide all notifications, iterate over the notifications in the state and call removeNotification(id) on each one: state.notifications.forEach(notif => removeNotification(notif.id)). Simply resetting the state would lead to the onDismiss callbacks not being fired.
    • It's entirely up to you to render the notifications. Connect to the store and iterate over them.
    • If your notifications need to have different styles or even different React components when rendering, use the kind to decide which component to render or which style to use.
    • Since notifications are stored in the Redux store, they should be serializeable. Avoid setting functions on notifications. Again, use the kind, pass any required information and handle it in the component rendering the notification.

    Install

    npm i @commercetools-frontend/notifications

    DownloadsWeekly Downloads

    1,259

    Version

    20.10.1

    License

    MIT

    Unpacked Size

    30.9 kB

    Total Files

    15

    Last publish

    Collaborators

    • tdeekens
    • emmenko
    • commercetools-admin