Giva Labs

jNotify jQuery Plug-in

Overview

The jQuery jNotify plug-in is an unobtrusive notification system for web-based applications. Use jNotify to inform users when specific actions have completed on your site–such as when an AJAX operation complete.

The jNotify plug-in is designed to replace code where you may have previously used the JavaScript alert() function to provide feedback to the user. The alert() function has two significant UI issues:

It is very obtrusive–users must take action (click "Ok") to remove the message or before you can interact with other elements on the page. While sometimes you want the user to acknowledge an action, often you just want to bring something to their attention without requiring them to take additional action.
You can not use rich-text–messages are limited to plain text only. Sometimes you want to provide rich-text features, such as links or images, in your notifications.

The jNotify plug-in provides a light-weight (3KB minified) solution to all of these problems.

Requirements

In order to use the jNotify plug-in, you need the following:

jQuery v1.2.6 (or higher)*
jquery.jnotify.js Plug-in

* This plug-in may work with older versions of jQuery in the 1.2 family. If you try using this with an older version of jQuery, you will need to include the jquery.dimensions.js plug-in (as of jQuery v1.2.6 the jquery.dimensions.js plug-in is included in the jQuery core.)

Usage

You can invoke a new notification using the following syntax:

$.jnotify(message, [options]);
$.jnotify(message, delay);
$.jnotify(message, sticky);
$.jnotify(message, type, [delay/sticky]);

Arguments

options: This argument is optional and allows you to customize the settings used for each instance of the plug-in. For a list of all available options, see the Options section.
delay: If the second argument is a number, then this is the same as setting the "delay" option.
sticky: If the second argument is either true or false, then this is the same as setting the "sticky" option.
type: If the second is a string, then this is the same as setting the "type" option.
delay/sticky: If the second is a string, then you can supply an optional third argument which specifies either the delay speed (a number) or if the notification is to be considered "sticky" (a boolean.).

Public API

$.jnotify.setup(options): Sets the default options to use for all jNotify notifications.
$.jnotify.pause(): Pauses any current non-sticky notifications from being removed from the queue.
$.jnotify.resume(): Resumes the notification queue if it has previously been paused.

Options

There are a number of options available for customizing the look and feel of the jNotify widget.

{
  // define core settings
    type: ""                                  // if a type is specified, then an additional class of classNotification 
                                              // + type is created for each notification
  , delay: 2000                               // the default time to show each notification (in milliseconds)
  , sticky: false                             // determines if the message should be considered "sticky" (user 
                                              // must manually close notification)
  , closeLabel: "&times;"                     // the HTML to use for the "Close" link
  , showClose: true                           // determines if the "Close" link should be shown if notification is also sticky
  , fadeSpeed: 1000                           // the speed to fade messages out (in milliseconds)
  , slideSpeed: 250                           // the speed used to slide messages out (in milliseconds)
  
  // define the class statements
  , classContainer: "jnotify-container"       // className to use for the outer most container--this is where all the 
                                              // notifications appear
  , classNotification: "jnotify-notification" // className of the individual notification containers
  , classBackground: "jnotify-background"     // className of the background layer for each notification container
  , classClose: "jnotify-close"               // className to use for the "Close" link
  , classMessage: "jnotify-message"           // className to use for the actual notification text container--this is 
                                              // where the message is actually written

  // event handlers
  , init: null                                // callback that occurs when the main jnotify container is created
  , create: null                              // callback that occurs when when the note is created (occurs just before 
                                              // appearing in DOM)
  , beforeRemove: null                        // callback that occurs when before the notification starts to fade away
  , remove: null                              // callback that occurs when notification is removed
  , transition: null                          // allows you to overwrite how the transitions between messages are handled
                                              // receives the following arguments:
                                              //   container - jQuery object containing the notification
                                              //   message   - jQuery object of the actual message
                                              //   count     - the number of items left in queue
                                              //   callback  - a function you must execute once your transition has executed
                                              //   options   - the options used for this jnotify instance
}

Getting Started

The first thing we need to do is to load the required CSS stylesheet and the JavaScript libraries used by the widget:

<!---// load the jNotify CSS stylesheet //--->
<link type="text/css" href="./css/jquery.jnotify.css" rel="stylesheet" media="all" />

<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script>
<script type="text/javascript" src="./lib/jquery.jnotify.js"></script>

Once you've added the jNotify plug-in to your HTML page, all you need to do is to invoke the $.jnotify() method whenever you want to display a message to the user.

Examples

[Run] $.jnotify("This is a default notification.");

[Run] $.jnotify("This is a notification with a 5 second delay.", 5000);

[Run] $.jnotify("This is a sticky notification.", true);

[Run] $.jnotify("This is an \"warning\" notification.", "warning");

[Run] $.jnotify("This is an \"error\" notification.", "error");

[Run] $.jnotify("This is a sticky \"error\" notification.", "error", true);

[Run]

$.jnotify("This notification shows an alert() when the notification is removed.", {remove: function (){ alert('removed!');}});

The plug-in has been designed to use CSS to all formatting and layout of the notification system. Try clicking the buttons below to see how easily you can change the default styles just by changing the CSS.

Support

This source code is provided as-is. At this time Giva is not offering direct support for this product. If you are in need of assistance, post your question to one of the jQuery Mailing Lists. Members of the Giva development team actively participate on the jQuery Mailing lists, so if we see your question we will try our best to respond.

License

Copyright 2010 Giva, Inc. (http://www.givainc.com/labs/) 

Licensed under the Apache License, Version 2.0 (the "License"); 
you may not use this file except in compliance with the License. 
You may obtain a copy of the License at 
	http://www.apache.org/licenses/LICENSE-2.0 

Unless required by applicable law or agreed to in writing, software 
distributed under the License is distributed on an "AS IS" BASIS, 
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
See the License for the specific language governing permissions and 
limitations under the License.

Download

The following download includes both uncompressed and minified versions of the plug-in and all the CSS and image files required to get you started. See the gettingstarted.htm file for usage instructions and a working example.

jquery.jnotify.zip (12 KB)

Revisions

v1.1.00 (2010-09-30)

Initial release

Home | Contact | About Giva | Privacy Policy | Terms of Use