gennotif v1.0.2
Generic Notification Interface
A generic interface that uses transports to deliver notifications to clients.
Examples
Sending a simple email:
var config = {
transports: ['email'],
data: {
from: 'you@example.com',
to: 'recipient@example.com',
subject: 'A new email message',
text: 'Lorem ipsum.',
html: '<b>Lorem</b> ipsum.'
}
}
var notification = new Notification(config);
notification.send();
Using fallback transports:
This will use multiple transports to send the notification. It will each of them (first to last) until one of them will successfully deliver the notification.
var config = {
transports: ['email', 'console'],
data: {
from: 'you@example.com',
to: 'recipient@example.com',
subject: 'A new email message',
text: 'Lorem ipsum.',
html: '<b>Lorem</b> ipsum.'
}
}
var notification = new Notification(config);
notification.send();
The console transport uses the only the "text" field from the data object.
Using multiple transports:
This notification will be send using all of the available transports. It does this synchronously.
var config = {
transports: ['email', 'console'],
data: {
from: 'you@example.com',
to: 'recipient@example.com',
subject: 'A new email message',
text: 'Lorem ipsum.',
html: '<b>Lorem</b> ipsum.'
}
}
var notification = new Notification(config);
notification.setStrategy(Notification.STRATEGY_ALL);
notification.send();
Reusing the "notification" object:
The config of the notification object can be change for individual notifications in order to not instantiate a new Notification instance.
var config = {
transports: ['email', 'console'],
data: {
from: 'you@example.com',
to: 'recipient@example.com',
subject: 'A new email message',
text: 'Lorem ipsum.',
html: '<b>Lorem</b> ipsum.'
}
}
var notification = new Notification(config);
notification.setStrategy(Notification.STRATEGY_ALL);
notification.send();
notification.send({
data: {
text: 'Different text for this notification',
html: '<b>Different</b> <i>text</i> for this notification'
}
});
Creating a custom transport:
Custom transports can be created by inheriting the NotificationTransportBase and implementing a "handle" method.
var Notification = require('gennotif').Notification;
var NotificationTransportBase = require('gennotif').NotificationTransportBase;
var util = require('util');
var CustomTransport = function() {
// execute the super_ constructor
NotificationTransportBase.apply(this, arguments);
// do your constructor magic
}
util.inherits(CustomTransport, NotificationTransportBase);
module.exports = CustomTransport;
CustomTransport.prototype.handle = function(data, cb) {
// you get the data part of the config
// send the notification using this transport and than call cb(err, results) when ready
cb();
}
Using the new transport:
var CustomTransport = require('./path/to/CustomTransport');
// Register this new transport
Notification.registerTransport('MyCustomTransport', CustomTransport);
// Use it
var config = {
transports: ['MyCustomTransport', 'console'],
data: {
text: 'Using my custom transport'
}
}
var new_notification = new Notification(config);
new_notification.send();
API
Class: Notification
Notification.registerTransport(name, TransportObject)
Registers a new transport with the Notification interface.
- name
String
the name of the transport that will be used in the config TransportObject
NotificationTransportBase
the object that extends the NotificationTransportBase used to send the notification
Notification.STRATEGY_LR
Default delivery strategy. Tries to deliver the notification using each transport starting with the first and stops after the first successful delivery.
Notification.STRATEGY_ALL
Tries to deliver the notification using all configured transports. This is done synchronously.
Notification.STRATEGY_RL
Same as Notification.STRATEGY_LR
but starts with the last added transport.
new Notification(config)
Create a new notification instance.
config
Object
- notifications
Array
of notification names that could be used - data
Object
basic configuration for the transports
- notifications
notification.setStrategy(strategy)
Set the delivery strategy for this notification. Possible values:
- Notification.STRATEGY_LR
- Notification.STRATEGY_ALL
Notification.STRATEGY_RL
notification.addTransport(name);
Adds a transport to the list of used transports. Has to be an already registered transport.
name
String
Name of the transport.
notification.removeTransport(name);
Removes a transport from the list of used transports.
name
String
Name of the transport.
notification.send(data)
Send the notification. The data part of the config used at construction time can be changed by using the data
arg.
- data
Object
Optional. Overwrites the data config.