ng-n

Fully customizable notification module for your AngularJS application.

Homepage

Angular Core Dependency: ~1.3.1

Module License: MIT

Added by: Sam Deering

GitHub

Repository

robinbressan/ng-n

Stats

Stars: 18

Watchers: 18

Forks: 1

Module Description

ngN Build Status

Fully customizable notification module for your AngularJS application.

See demo: http://jsfiddle.net/RobinBressan/ege3gu9c

Installation

It is available with bower:

bower install ng-n

Then add the retrieved files to your HTML layout:

<script type="text/javascript" src="/path/to/bower_components/ng-n/ng-n.min.js"></script>

You can also use it with RequireJS as an AMD module.

Then add ngN as dependency for your AngularJS application:

var app = angular.module('YOUR_APP', ['ngN']);

Usage

To build a notification simply use $n factory:

var notification = $n({ title: 'Success', content: 'It works!'});

// You can configure it before display it
notification
    .title('Error') // You can update the title
    .timeout(2000) // It will expire after 2000ms
    .save(); // We save the notification to display it

// Each property can be retrieved by calling the same function without argument
notification.title(); // Will return `Error`

In fact, we've used here title or content but you can use whatever you want:

var notification = $n({ spaceship: 'Success' });

notification.spaceship(); // Will return `Success`
notification.spaceship('Info'); // Will set spaceship to `Info`

A notification always has some persistent methods:

  • on(event, callback): Add an event listener
  • trigger(event): Call all event listeners for a given event
  • kill(): Mark the notification as expired
  • save(): Save the notification. It means it will be displayed if not expired
  • timeout(time): Auto kill the notification when timeout ends

Furthermore you can give a delay to the save method:

var notification = $n();

notification.save(3000); // Will be save in 3000ms

When a notification is saved, the save event is triggered. Same thing for kill method:


var notification = $n();

notification
    .on('save', function() {
        storeToDatabase();
    })
    .on('kill', function() {
        removeFromDatabase();
    });

// You can also define you own events

notification
    .on('something', function() {
        console.log('something happens');
    })
    .trigger('something');

Custom notification factories

You can also create a custom $n factory by using $n.extend:

var customN = $n.extend({ title: 'default title'});

var notification = customN(); // notification has now a `title` method

Or better idea:

var withContent = $n.extend({ content: '' });

var info = withContent.extend({ title: 'Info' });
var success = withContent.extend({ title: 'Success' });
var error = withContent.extend({ title: 'Error' });

// Let's display an information
info().content("What's up").save();

// Or an error
error().content('Oups').save();

// And a success
success().content('You did it!').save();

And what about registering this custom factories in angular DI? Let's do it:

var app = angular.module('myApp', ['ngN']);

app.factory('withContent', ['$n', function($n) {
    return $n.extend({ content: ''});
}]);

app.factory('info', ['withContent', function(withContent) {
    return withContent.extend({ title: 'Info' });
}]);

app.factory('error', ['withContent', function(withContent) {
    return withContent.extend({ title: 'Error' });
}]);

app.factory('success', ['withContent', function(withContent) {
    return withContent.extend({ title: 'Success' });
}]);
Notification stack

Since v1.2 you can group some notifications into a stack. A stack will be dispatched as a single notification but with a flush method to dispatch all its notifications:

    var myStack = $n.stack();

    var notification1 = $n({ content: 'I am stacked!'});
    myStack.push(notification1);

    var notification2 = $n({ content: 'I am stacked too!'});
    myStack.push(notification2);

    // The stack contains two notification. To create the stacked notification just call it as a function
    myStack()
        .timeout(5000)
        .save();

A stack exposes two new methods:

  • size(): Return a the notification count stored into the stack
  • flush(): Dispatch all notifications stored into the stack and empty it

When a stacked notification is flushed, the flush event is triggered:


myStack()
    .on('flush', function() {
        markAsRead();
    });

To handle display for a stack, see Display the notifications.

Display the notifications

To display the notifications you have to use the n-view directive:

<n-view>
    <!-- You can define your notification template here.
        It will be used for each notification available -->

    <!--`notification` targets the current one -->
</n-view>

For example you can do:

<n-view>
    <div class="alert">
        <h4>{{ notification.title() }}</h4>
        <p>
            {{ notification.content() }}
            <a ng-click="notification.kill()">Close</a>

            <!-- You can add a listener on this `cancel` event by using `on` method on your notification definition -->
            <!-- This way you are free to add any custom behaviour! -->
            <a ng-click="notification.trigger('cancel').kill()">Cancel</a>
        </p>
    </div>
</n-view>

Or maybe using the bootstrap angular-ui alert directive:

<n-view>
    <alert type="{{ notification.type() }}" close="notification.kill()">{{ notification.content() }}</alert>
</n-view>

You can also use a ng-include directive inside a ng-view:

<n-view>
    <ng-include src="'template.html'"></ng-include>
</n-view>
Display a stacked notification

A stacked notification is displayed the same way than a classic notification. You can detect it by checking if the flush method is defined:

<n-view>
    <div class="alert" ng-if="!notification.flush">
        <h4>{{ notification.title() }}</h4>
        <p>
            {{ notification.content() }}
            <a ng-click="notification.kill()">Close</a>

            <!-- You can add a listener on this `cancel` event by using `on` method on your notification definition -->
            <!-- This way you are free to add any custom behaviour! -->
            <a ng-click="notification.trigger('cancel').kill()">Cancel</a>
        </p>
    </div>
    <div class="alert" ng-if="!notification.flush">
        <!-- We are in a stacked notification -->
        <h4>{{ notification.size() }} notifications</h4>
        <p>
            <!-- You can display all notifications in the stack by calling the `flush` method -->
            <a ng-click="notification.flush()">Show all</a>
            <a ng-click="notification.kill()">Close</a>
        </p>
    </div>
</n-view>

Build

To rebuild the minified JavaScript you must have requirejs installed globally and run: make build.

Tests

Install dependencies and run the unit tests:

make install
make test-spec

Contributing

All contributions are welcome and must pass the tests. If you add a new feature, please write tests for it.

License

This application is available under the MIT License.

Module stats last updated: 2017-03-18 16:00:05

Disclaimer: Some data on this page may have been gathered from the authors GitHub respository. If you see any mistakes or outdated information please let us know. Thanks!