uNotify

Highly customizable javascript library for Growl-like notifications.

Download | Github
Requires jQuery

Why do we need another notify library?

We likely don't, but I do. Existing libraries codified too much of the composition of the notification element, making it difficult or impossible to change without re-writing the library - which causes havoc when updating said library.

uNotify is my attempt at making a simple notification library that gives the developer as much customization as possible external to the library. You can customize pretty much every aspect of how a notification behaves, but you are also exposed to the complexity that customization requires.

Usage

Configure library 
uNotify.setDefaults({Configuration object});

Create notification 
uNotify.notify('Type of message','Text of message',[Configuration object]);

Options

Most options can be passed in an object to both setDefaults() and notify(). When passed to setDefaults(), all future notifications will use the passed values as defaults. When passed to notify(), the passed values will only apply to the current notification.

If configuring globally, it might just be easier to directly set those defaults. For example, if you want to set the default text that appears in the dismiss button:

it may be easier to: 
uNotify.defaults.dismiss.text = 'Okay';
rather than: 
uNotify.setDefaults({
	dismiss:{
		text: 'Okay'
	}
});
Option Global
Config		 Individual
Config
classes

Defines the different types of notifications that can be displayed.

Object properties are strings that would get passed as the first argument to Notify.notify(). Object values are the classes that get added to the notification.

The defaults of info,danger,warning, and success map to the corresponding Bootstrap 3 classes.

Default 
classes:{
	'info': 	'alert alert-info',
	'danger': 	'alert alert-danger',
	'warning': 	'alert alert-warning',
	'success': 	'alert alert-success'
}
 Yes Yes, but not ideal.
dismiss An object that defines the dismiss button options, if the message is dismissable (as opposed to automatically timing out) Yes Yes
markup The markup of the dismissing element.
Default 
<button class = "btn btn-xs btn-default notify-dismiss"></button>
selector The jQuery selector string used to find the dismissing element within the context of the notification element.
Default 
.unotify-dismiss
text The text that should appear in the button. Note that this string is always injected into the button, so don't put text in the markup.
Default 
OK
addContent The function that gets run when injecting the dismiss element's content into the dismiss element. The function is passed the content of the dismiss element as the sole argument. this refers to a jQuery object that represents the dismiss element.
Default 
function(content){
	this.text(content);
}
add The function that gets run when inserting the dismiss element the notification element. The function is passed a jQuery object representing the dismiss element. this refers to a jQuery object that represents the notification element.
Default 
function($dismiss){
	$dismiss.appendTo(this);
}
notify Options for all notifications Yes Yes, but why?
markup The markup used to generate each notification. Classes get added to this markup from the classes and additional_classes options, so the only classes that should get added here are those that need to be added to all notifications.
Default 
<div></div>
wrapper All notifications get added to a wrapper element, to help place them on the page. This object defines properties for that wrapper Yes No
markup The markup used for the wrapper. Note the default has an ID set, as the wrapper must be unique.
Default 
<div id = "notify-wrapper"></div>
parent A jQuery selector string used to select the element on the page into which the wrapper should be placed.
Default
body
selector A jQuery selector string used to select the wrapper element.
Default 
#unotify-wrapper
style Additional css declarations that get added to the wrapper markup. This style isn't added to the default wrapper markup because you may want to change the style, but not the markup. Both can be changed, though, if you want.
Default 
position:fixed;
top:20px;
right:20px;
message Properties of the individual notification that can be passed to notify() Yes Yes
additional_classes Additional css declarations that get added to the notification element. For example, you may want to add CSS classes for animating in via Animate.css.
Default
Empty string
additional_dismiss_classes Additional css declarations that get added to the dismiss element if it exists. For example, this could be used to coordinate the look of the button to match the type of notification.
Default
Empty string
dismissable Whether or not this notification should be dismissable (ie: sticks around until user clicks the dismiss button)
Default
false (notifications disappear on their own by default)
timeout How long (in milliseconds) the notification should appear for. This is ignored if dismissable is set to true.
Default
3000
addContent The function used to inject the message into the notification. The function is passed the content as the sole argument. this refers to the jQuery object representing the notification element
Default 
function(content){
	this.text(content);
}

Event options

The options object can also contain an on object that defines event listeners. Due to the possible asynchronous nature of your event listeners, most listeners must trigger the event for the next listener. The event chain is as follows:

When showing

beforeShow.unotify

show.unotify

afterShow.unotify

When hiding

dismiss.unotify

timeout.unotify

beforeHide.unotify

hide.unotify

afterHide.unotify

As you might guess, each function must trigger the next event in the chain. Optionally, you can purposfuly not trigger the next event in order to cancel the action.

Each function will be called in the context of the notification element, so this will refer to the jQuery object that represents the notification element.

Any of these functions can be defined both globally and on a notification-by-notification basis

Option Event to trigger
dismiss A function that gets run when the dismiss button is clicked, which can be used to trigger an animation or some other action.
Default 
function(){
	this.trigger('beforeHide.unotify');
}
 beforeHide.unotify
timeout A function that gets run when the timeout timer on the notification has elapsed.
Default 
function(){ 
	this.trigger('beforeHide.unotify'); 
}
 beforeHide.unotify
beforeShow A function that gets run before the notifcation begins to appear.
Default 
function(){
	this.trigger('show.unotify');
}
 show.unotify
show A function that gets run when the notification should start to appear. This function is responsible for actually showing the notification.
Default 
function(){
	this.show();
	this.trigger('afterShow.unotify');
}
 afterShow.unotify
afterShow A function that gets run after the notification is completely done appearing. This function is responsible for triggering the beginning of the timeout timer. If a notification is dismissable, the startTimeout.unotify event can still be triggered, it just won't have any effect.
Default 
function(){
	this.trigger('startTimeout.unotify');
}
 startTimeout.unotify
beforeHide A function that gets run before the notifcation begins to disappear
Default 
function(){
	this.trigger('hide.unotify');
}
 hide.unotify
hide A function that gets run when the notification should start to disappear. This function is responsible for actually hiding the notification.
Note how the callback function has this mapped to the this of the function. This is because it is necessary to maintain the context inside the callback function.
Default 
function(afterHide){
	this.slideUp(500,function(){
		this.trigger('afterHide.unotify');
	}.bind(this));
}
 afterHide.unotify
afterShow A function that gets run after the notification is completely done appearing. This function is responsible for triggering the beginning of the timeout timer. If a notification is dismissable, the startTimeout.unotify event can still be triggered, it just won't have any effect.
Default 
function(){
	this.trigger('startTimeout.unotify');
}
 startTimeout.unotify

Option defaults

Here are all the options and their defined defaults: 

defaults: {
	classes:{
		'info': 	'alert alert-info',
		'danger': 	'alert alert-danger',
		'warning': 	'alert alert-warning',
		'success': 	'alert alert-success'
	},
	dismiss:{
		markup:'',
		selector:'.unotify-dismiss',
		text: 'OK',
		addContent:function(content){
			this.text(content);
		}
	},
	notify:{
		markup: '
',
	},
	wrapper:{
		markup: '
',
		parent: 'body',
		selector: '#unotify-wrapper',
		style: 'position:fixed;top:20px;right:20px;'
	},
	message:{
		additional_classes: '',
		additional_dismiss_classes: '',
		dismissable: false,
		timeout: 3000,
		addContent:function(content){
			this.text(content);
		}
	},
	on:{
		beforeShow:function(){
			this.trigger('show.unotify');
		},
		show:function(){
			this.show();
			this.trigger('afterShow.unotify');
		},
		afterShow:function(){
			this.trigger('startTimeout.unotify');
		},
		dismiss:function(){
			this.trigger('beforeHide.unotify'); 
		},
		timeout:function(){ 
			this.trigger('beforeHide.unotify'); 
		},
		beforeHide:function(){
			this.trigger('hide.unotify');
		},
		hide:function(afterHide){
			this.slideUp(500,function(){
				this.trigger('afterHide.unotify');
			}.bind(this));
		},
		afterHide:function(){
		}
	}
}

Examples

Note: Examples that show how to set options globally use a duplicated uNotify object. Its not possible to have multiple different, concurrent global uNotify settings.
Simple usage 



$("#ex-2-info").on('click',function(){
	uNotify.notify('info','This is an info notification.');
});
$("#ex-2-danger").on('click',function(){
	uNotify.notify('danger','This is a danger notification.');
});
$("#ex-2-success").on('click',function(){
	uNotify.notify('success','This is a success notification.');
});
$("#ex-2-warning").on('click',function(){
	uNotify.notify('warning','This is a warning notification.');
});
Custom type 
uNotify.setDefaults({
	classes:{'purple':'alert alert-purple'}
});
$("#ex-3").on('click',function(){
	uNotify.notify('purple','This is a purple notification.');
});
Dismissable 
$("#ex-4").on('click',function(){
	uNotify.notify('danger','Click me to hide',{
		message:{
			dismissable: true
		}
	});
});

You'll note how the dismiss button is right smack up against the text. To preserve full customizability, uNotify doesn't do anything automatically to give it space. A simple declaration in your CSS like: 

.unotify-dismiss{ margin-left:10px; }
should give you something that looks a little more polished.

All subsequent dismissable examples will be spaced properly because it just looks better. Remember you have to add that styling yourself though.

Dismissable with custom text 
$("#ex-5").on('click',function(){
	uNotify.notify('danger','Click me to hide',{
		message:{
			dismissable: true
		},
		dismiss:{
			text:'Go away!'
		}
	});
});
Dismissable with close button and close button content injection 
$("#ex-6").on('click',function(){
	uNotify.notify('success','Click me to hide',{
		message:{
			dismissable: true
		},
		dismiss:{
			markup: '<a class = "btn btn-default notify-dismiss"><span></span>!</button>',
			addContent:function(content){
				this.find('span').text(content);
			}
		}
	});
});
Note how the markup still has the unotify-dismiss class. This class is used by uNotify to know what element to listen to. If you wish to change that class, use the selector option.
Dismissable with custom add function 
$("#ex-65").on('click',function(){
	uNotify.notify('success','Click me to hide',{
		message:{
			dismissable:true
		},
		dismiss:{
			add:function($dismiss){
				$dismiss.prependTo(this);
			}
		}
	});
});
Changing the timeout 
$("#ex-7").on('click',function(){
	uNotify.notify('success','Success is fleeting',{
		message:{
			timeout:500
		}
	});
});
Changing where the notifications appear 
$("#ex-8").on('click',function(){
	uNotify.setDefaults({
		wrapper:{
			style: 'position:fixed;bottom:20px;right:20px;'
		}
	});
	uNotify.notify('success','In the bottom corner');
});
Adding additional classes at run-time 
$("#ex-9").on('click',function(){
	uNotify.notify('warning','Thick',{
		message:{
			additional_classes: 'heavy'
		}
	});
});
Note: .heavy is just a class made up for this example - it's not part of Bootstrap 3 or uNotify.
Adding additional classes to the dismiss button at run-time 
$("#ex-10").on('click',function(){
	uNotify.notify('info','Colour co-ordinated',{
		message:{
			dismissable:true,
			additional_dismiss_classes:'btn-info'
		}
	});
});
Note: .heavy is just a class made up for this example - it's not part of Bootstrap 3 or uNotify.
Custom events

This example uses animate.css animation classes to show and hide the notification, rather than jQuery.

jQuery is still used to shrink the space occupied by the notification, because animate.css just animates the element, it doesn't remove it 

$("#ex-11").on('click',function(){
	uNotify.notify('success','Ta da!',{
		message:{
			additional_classes: 'animated'
		},
		on:{
			show:function(){
				this.addClass('bounceInDown');
				this.trigger('afterShow.unotify');
			},
			hide:function(){
				this.addClass('fadeOutUp');
				this.trigger('afterHide.unotify');
			},
			afterHide:function(){
				this.slideUp();
			}
		}
	});
});

Styling

By default uNotify uses Bootstrap 3 alert classes. If you want to change that, or add new classes, just change the classes option.

Additionally, classes can be added to any notification using the additional_classes option.

Styling the wrapper

If you're loathe to have inline CSS, you can add a #unotify-wrapper entry to your CSS, and remove the uNotify.defaults.wrapper.style property.