Missing growl.js tutorial

In 2010 I created small JavaScript library for in-browser “notifications”. Though its API was documented, no tutorial was written. Actually, this is not surprising, as growl.js is unpopular even at Original Coding: it was used in several projects, and then focus shifted to projects where work is 90% backend. But I wouldn’t be writing this just to say that, right? I prepared short introduction to library, just in case you need to understand how to use it. But it’s still better to use something modern, e.g. some React component.

First of all, there is a complete demo—check it out. Basically, it contains two “panels” (green and red): each has text input and button. You type some text into input, press button, and new notification is added. Each notification type has its own settings that define its behaviour. Two types of notifications are defined in demo: success and error. “Success” notifications are shown for 5 seconds, and then disappear. “Error” ones stay on page until you “close” them. Now let’s look at the code.

At the bottom of main.js there is following:

var growl = new Growl({
    element: growlEl,
    types: {
        error: {sticky: true},
        success: {sticky: false, timeout: 5000}
    },
    bind: true,
    add: addGrowlMessage,
    remove: removeGrowlMessage
});

As you can see, new instance of Growl class is created and some options (growl.js calls them “settings”) are passed:

element

This is container for all notifications. It can be HTMLElement (like in demo), jQuery-wrapped HTMLElement, or anything else.

types

Each notification has type (e.g. success), and this is where you define both types and their settings. sticky notifications are not removed automatically. Non-sticky notifications are removed after timeout (in milliseconds) is passed (removal is done by call to remove function which is described below).

add

This is a function that accepts element, notification message (which in demo is taken from text input’s value), and settings (so you can get type of notification via settings.type); it returns notification element (anything you want, as you handle it in remove) that will be passed to remove. It does what you make it to do: in demo I create new div, add classes, set its innerHTML, and add to element. For sticky notifications I also create span with click handler that removes notification element from element.

remove

This is a function that accepts element, notification element (whatever you returned from add), and settings; it doesn’t return anything. It does what you make it to do: in demo I remove notification element from element (and if after that element contains no notification elements, the former is hidden).

bind

If bind is true, growl.js adds shortcuts for addNotification method, so notifications could be added via growl[type of notification]("Hello!", extra settings).

Look at code from demo:

growl.success("Page is loaded.", {timeout: 1000});

This is equivalent to following:

growl.addNotification("Page is loaded.", {type: "success", timeout: 1000});

After Growl instance is created, you can use it to add notifications with shortcuts (e.g. growl.error("Put the cookie down!")) or with addNotification (like I do in setUpPanel function in main.js):

var val = messageInputEl.value.trim();
if (val) {
    growl.addNotification(val, {type: type});  // type is string, like "error" or "success"
}

And that’s it. For “how it may look” look at the demo, for “how it’s done” see main.js.