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.4.3 (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)
    , clickToDismiss: true         // allows you to click on a message to dismiss it
    , closeLabel: "&#x2716;"       // the HTML to use for the "Close" link
    , showClose: true              // determines if the "Close" link should be shown
                                   // if notification is also sticky
    , fadeSpeed: 250               // 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="https://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 sticky \"error\" notification.", "error");

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

[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.

License

Copyright 2013 Giva (https://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
    https://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.

Revisions

v1.3.01 (2017-05-15)

The clickToDismiss is now applied to sticky items
Updated close text to heavy multiplication X unicode character (U+2716)
Updated default styles (original styles available in jquery.jnotify-original.css)
Reduced fadeSpeed from 1000ms to 250ms
Fixed issue where dismissing a sticky notification was not using the correct effects
Long lines are now text aligned left, but shorter messages are still centered

v1.3.00 (2017-05-08)

Passing "error" as the option will now default to generating a sticky notification
Fixed bug when passing "options" as a string, the third argument now correctly populates either the delay (numeric value) or sticky (boolean value)

v1.2.00 (2014-07-10)

Added clickToDismiss option for clicking a message to quickly dimiss the message
Fixed issue where messages would sometimes fadeout incorrect due to issue with items not removed from queue correctly

v1.1.02 (2013-09-19)

Fixed option.create callback to not run until after note is added to the DOM
The option.create callback now also gets an argument referencing the $jnotify layer

v1.1.00 (2010-09-30)

Initial release

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)