Unit tests:

Meteor notifications

Add tooltip-style reactive notifications to your Meteor application. Makes use of Meteor's rendering system; not just a jQuery/bootstrap wrapper.

See example page @ meteor.com source: github.com

Installation

$ meteor add gfk:notifications

FAQ

How do I make the notifications stay in the top corner of the viewport?

If you want a notification to always be visible within the viewport of the browser even when the user scrolls, you should set the position of the notifications wrapper div to fixed.

Add the following CSS to your application:

ul.notifications {
position: fixed;
}

How do I push notification from server side?

You can use the server-messages package for that. The example page is setup for the usecase of notifications with this package source

First add gfk:server-messages to your application

meteor add gfk:server-messages

Then add the following code to your application:

Shared:

serverMessages = new ServerMessages();

Client:

  serverMessages.listen('serverMessage:info', function (subject, message, options) {
    Notifications.info(subject, message, options);
  });

  serverMessages.listen('serverMessage:warning', function (subject, message, options) {
    Notifications.warn(subject, message, options);
  });

  serverMessages.listen('serverMessage:success', function (subject, message, options) {
    Notifications.success(subject, message, options);
  });

  serverMessages.listen('serverMessage:error', function (subject, message, options) {
    Notifications.error(subject, message, options);
  });

Now you can push a notification to the server with the following code on the server:

serverMessages.notify('serverMessage:error', 'Error subject', 'Error message');

Contributing

All contributions are welcome! Please submit pull requests. Please add tests and make sure everything is green!

Testing

Unit tests

To run the unit tests execute the following command from within your checkout:

meteor test-packages ./

UI tests

To make my life and yours easier I've also created some basic UI tests for this project. They are stored in the meteor-notifications-example repository.

After each new version the example page is updated to use the latest version, after which travis runs the UI tests. But you can ofcourse also run them locally.

Clone the example page repo
From within your checkout run the following commands:

mkdir -p app/packages
ln -s #YourNotificationsPackageCheckoutDirectory# app/packages/gfk:notifications

Make sure you have the example page running on port 3000
From within the example page repo checkout run: ```nightwatch -c firefoxDev

The example page is also a good place to debug/check your new functionality. Consider adding a example of the new functionality and creating a PR for that too!

API

Basics

To create a notification

First add the following to the template you want to be the parent for your notifications.

{{> notifications}}

Then run the following code in your application to spawn a notification of the type of the method you use to spawn it:

1Notifications.warn('title', 'message');
2Notifications.error('title', 'message');
3Notifications.info('title', 'message');
4Notifications.success('title', 'message');

Changing default settings

To change the animation speed or the hideAnimationProperties, you need to change the Notifications.settings object.

Example:

1Meteor.startup(function () {
2    Notifications.settings.animationSpeed = 500;
3});

Default options to be used for each notification can be changed in the Notifications.defaultOptions object.

Example:

1Meteor.startup(function () {
2    _.extend(Notifications.defaultOptions, {
3        timeout: 5000
4    });
5});

Optionally, you can also provide type-specific options by changing the Notifications.defaultOptionsByType object.

1Meteor.startup(function () {
2    //Give Error notifications a longer timeout
3    Notifications.defaultOptionsByType[Notifications.TYPES.ERROR] = _.defaults({
4        timeout: 10000
5    },
6    Notifications.defaultOptions);
7});

Restyling the notifications

To restyle the notifications check the styleSheet and create your own stylesheet that overrides the classes defined in the bundled style. For instance, if you want to make the success notifications red you would add the following:

1li.notification {
2    &.success {
3        background-color: #F00;
4    }
5}

Notifications()

Creates an instance of Notifications.

addNotification(title, message, [options={}])

Adds a notification.

Params:

String title of the notification
String message of the notification
Object [options={}] Options object to use for notification
String [options.type=defaultOptions.type] the type of the notification
Boolean [options.userCloseable=defaultOptions.userCloseable] Whether the notification is user closeable
Boolean [options.clickBodyToClose=defaultOptions.clickBodyToClose] Whether the notification can be closed by clicking anywhere in the body. If turned off then the user must click the close button.
Number [options.timeout=defaultOptions.timeout] No. of milliseconds after which this notification should automatically be closed. Use 0 to disable this.
Function [options.closed] Call this handler (passing data context) on notification close
Function [options.onBodyClick] Call this handler (passing data context) on notification body click

Returns:

String id of the added notification.

error(title, message, [options={}])

Wraps addNotification, sets type to error.

Params:

String title of the notification
String message of the notification
Object [options={}] Options object to use for notification
Boolean [options.userCloseable=defaultOptions.userCloseable] Whether the notification is user closeable
Boolean [options.clickBodyToClose=defaultOptions.clickBodyToClose] Whether the notification can be closed by clicking anywhere in the body. If turned off then the user must click the close button.
Number [options.timeout=defaultOptions.timeout] No. of milliseconds after which this notification should automatically be closed. Use 0 to disable this.
Function [options.closed] Call this handler (passing data context) on notification close
Function [options.onBodyClick] Call this handler (passing data context) on notification body click

Returns:

String id of the added notification.

warn(title, message, [options={}])

Wraps addNotification, sets type to warning

Params:

String title of the notification
String message of the notification
Object [options={}] Options object to use for notification
Boolean [options.userCloseable=defaultOptions.userCloseable] Whether the notification is user closeable
Boolean [options.clickBodyToClose=defaultOptions.clickBodyToClose] Whether the notification can be closed by clicking anywhere in the body. If turned off then the user must click the close button.
Number [options.timeout=defaultOptions.timeout] No. of milliseconds after which this notification should automatically be closed. Use 0 to disable this.
Function [options.closed] Call this handler (passing data context) on notification close
Function [options.onBodyClick] Call this handler (passing data context) on notification body click

Returns:

String id of the added notification.

info(title, message, [options={}])

Wraps addNotification, sets type to info

Params:

String title of the notification
String message of the notification
Object [options={}] Options object to use for notification
Boolean [options.userCloseable=defaultOptions.userCloseable] Whether the notification is user closeable
Boolean [options.clickBodyToClose=defaultOptions.clickBodyToClose] Whether the notification can be closed by clicking anywhere in the body. If turned off then the user must click the close button.
Number [options.timeout=defaultOptions.timeout] No. of milliseconds after which this notification should automatically be closed. Use 0 to disable this.
Function [options.closed] Call this handler (passing data context) on notification close
Function [options.onBodyClick] Call this handler (passing data context) on notification body click

Returns:

String id of the added notification.

success(title, message, [options={}])

Wraps addNotification, sets type to success

Params:

String title of the notification
String message of the notification
Object [options={}] Options object to use for notification
Boolean [options.userCloseable=defaultOptions.userCloseable] Whether the notification is user closeable
Boolean [options.clickBodyToClose=defaultOptions.clickBodyToClose] Whether the notification can be closed by clicking anywhere in the body. If turned off then the user must click the close button.
Number [options.timeout=defaultOptions.timeout] No. of milliseconds after which this notification should automatically be closed. Use 0 to disable this.
Function [options.closed] Call this handler (passing data context) on notification close
Function [options.onBodyClick] Call this handler (passing data context) on notification body click

Returns:

String id of the added notification.

getNotificationClass(notificationType)

Gets the class containing the color for the notification

Params:

String notificationType

remove(selector)

Removes the notifications matching the mongo query selector

Params:

selector Mongo query selector

Example:

1// Create Notification
2var notificationId = Notifications.success('title', 'message');
3// Remove exisiting notification sometime between [0,5) seconds
4Meteor.setTimeout( function () {
5    Notifications.remove({ _id: notificationId });
6}, Math.Random() * 5000 );

TYPES

Stores constants for the different notification types

defaultOptions

Object with the default options for the notifications

defaultOptionsByType

Object with the default options for the notifications for specific types