angular-alert-me

a notification manager for angularjs with many options

DEMO

Getting started

Download the module using npm or bower:

npm install --save angular-alert-me
bower install --save angular-alert-me

or download it from github.

Add the style and the script to your html page:

<link rel="stylesheet" type="text/css" href="angular-alert-me.css">
<script type="text/javascript" src="angular-alert-me.js"></script>

Add module name to your application dependencies:

angular.module('app', ['alert-me']);

That's it now you can inject anywhere in your app the AlertMe service in order to manage the notifications.

---

How to use it

Let's start by creating a simple default notification using the create function, this method will return the message just created:

angular.module('app')
.controller('MainCtrl', function(AlertMe) {
  AlertMe.create('a simple alert').then(function(message) {
    console.log('Message created:', message);
  });
});

You can use the create function in two ways:

• Passing a string will output the default alert message with the string you passed as content.
• Passing a object with the attributes you want to override to customize the alert message appearance and beaviour, the mandatory property is content with is the message of the alert.

The default alert class is default, (not so fantasy) but you can create a fully customized alert your custom classes and doing your own style.

var msg = {
  content: 'a custom alert',
  className: 'my-class'
}

AlertMe.create(msg);

You can override the module defaults settings using configure method inside the config function:

angular.module('app')
.config(function(AlertProvider) {

  AlertProvider.configure({
    className: 'success' // this will be the default class if nothing is passed,
    onBeforeCreate: function(conf) {
      // do some checks
    }
  })

})

But you can always set override the properties per message passing a object to the create method, like in this example:

var msg = {
  content: 'another custom alert!',
  className: 'different',
  dismissOnClick: true, // by clicking it will dismiss the alert
  onDismiss: myCallBack // the callback to run when the alert is dismissed
}

function myCallback() { ... }

AlertMe.create(msg);

You can also use html text as content for your alerts, but be sure to add the isTrustedHtml flag property to your settings or to the message you want to be threated as html, like so:

var msg = {
  content: 'visit our <a href="#!">page</a> on github',
  isTrustedHtml: true // this will threat the content as html text
}

Also you can specify to use the default interceptor to notify all the HTTP request and responses errors.

angular.module('app')
.config(function($httpProvider) {
  $httpProvider.interceptors.push('alertInterceptor');
});

But you can always disable notifications for particular HTTP calls by setting the notifyError configuration option to false.

$http({url: '/api/something', notifyError: false});
$http.get('/api/something', {notifyError: false});
$http.post('/api/something', data, {notifyError: false});

Now you can also use the desktop notifications if supported by the browser, for now you must set it globally:

angular.module('app')
.config(function(AlertProvider) {
  AlertProvider.configure({ desktop: true });
});

Important:

In the new version 1.1.0 the create method (and also info, success, warning, danger) returns a Promise so you need to change the code if you want to upgrade from previous versions.

---

Methods

To all the methods listed below you can pass both a string or a object.

• create; The main method for creating alerts
• dismiss; Dismiss a message using his ID
• dismissAll; To dismiss all the messages at once
• info; This method will call create with default class 'info'
• success; This method will call create with default class 'success'
• warning; This method will call create with default class 'warning'
• danger; This method will call create with default class 'danger'

---

Configurable settings:

These settings can be edited using the method configure of AlertMe service.

• desktop: If true it will try to use the desktop notifications
• maxNum: max alerts to show ( default 0 = unlimited )
• verticalPosition: vertical alert container position (default 'bottom')
• horizontalPosition: horizontal alert container position (default 'right')
• className: the default alert class to use in case of nothing is specified
• isTrustedHtml: if the content has to been treated as HTML
• combineDuplications: combine duplicated alerts (default true)
• dismissButton: if the dismiss button is show (default true)
• dismissOnClick: the alert is dismissable by clicking on it (default true)
• dismissOnTimeout: the alert is dismissed with a timeout (default true)
• dismissTimeout: the dismiss timeout (in seconds)
• onBeforeCreate: the function that run after before the alert is created (default return true)
• onAfterCreate: the function that run after the alert has been created
• onBeforeDismiss: the function that run before dismissing the alert
• onDismiss: the function that run when the alert hsa been dismissed (1 arg)

See the examples section for more details about them.

---

Usage examples

Set the max simultaneous notification number to 10:

// Set the max alert number to 10:
AlertMe.configure({
  maxNum: 10
});

Show he dismiss button for all the alerts:

// Show he dismiss button for all the alerts:
AlertMe.configure({
  dismissButton: true
});

Error message with status code and text (assuming exist error object)

// Error message with status code and text
AlertMe.create({
  className: 'error',
  title: error.status,
  content: error.statusText
});

Do a fixed alert that can't be closed

// Do a fixed alert that can't be closed
AlertMe.create({
  content: 'This is very important.',
  dismissButton: false,
  dismissOnClick: false,
  dismissTimeout: false
});