stratease/dGrowl

# dGrowl

dGrowl is a simple notification system similar to the OS X's Growl notifications. The widget was built with the dojo 1.8.2 framework. This version takes advantage of the dojo AMD loader. There is also a similar dojo widget called a Toaster. dGrowl offers some desired features the Toaster lacked but it may still be a good choice depending on your needs.

Try it out below!

## Features

- Channels - a system for organization of various classifications of messages. A common usage example would be an "error" channel vs. an "info" channel. This allows custom styling for user defined channels, as well as grouping the notifications within their respective channel.
- Customizable Styles - there are several built in styles out of the box, but with the CSS class structure of the notification elements it makes it easy to modify to suit your needs.
- Sticky notices - you can determine any message to be important enough to wait until a user decides to close it by using the sticky flag.
- CSS3 animations - the built in stylesheet uses CSS transitions. This keeps it lightweight and more extensible.
- Built in Topic Subscription - utilizes dojo's topic module, which makes it easy to use from various scopes of your application. Create one dGrowl instance and publish your events from anywhere. If desired, you can use the addNotification procedural API as well.
- Event Hooks - built in onShow and onHide events for the notification widgets.

## Examples

A simple example.

    var dg = new dGrowl();
    dg.addNotification('Hello world!');

Creating two channels and publishing a `dGrowl` event.

    var dg = new dGrowl({'channels':[{'name':'info','pos':2},{'name':'error', 'pos':1}]});
    dg.addNotification('Ut oh, something broke!',{'channel':'error'});
    topic.publish('dGrowl', 'This message is stickied!', {'title':"Onward ho!", 'sticky':true});

## API

### dGrowl

`dGrowl([optionsl])`

Property | Datatype | Description
--- | --- | ---
`channels` | array | [optional] List of channel definitions. The first item in this list is the default channel when one isn't specified for the notifications. Object properties include: `pos` - integer [optional]. The display order. `name` - string. The channel name.
`defaultChannel` | string | [optional] The name of the default channel the `addNotification` method uses. When not specified, uses the first item in the channels list or default.
`orientation` | string | [optional] Defaults to topRight. This is the location on the window the widget is located. Available options: topRight, (planned: topLeft, bottomRight, bottomLeft)

### addNotification and dGrowl topic

#### Try it out!

`addNotification( String message, [options])`

Property | Datatype | Description
--- | --- | ---
`sticky` | boolean | [optional] Defaults to false. If true the notification will remain on the window until closed.
`duration` | integer | [optional] msecs the notification remains on the page. Defaults to 5000.
`channel` | string | [optional] Name of the channel this message is fired under.
`title` | string | [optional] A title displayed at the top of the message.