Angular Growl 2

Growl-like notifications for AngularJS

Code on Github Download (0.6.0)

Dependencies

This repository contains a AngularJS directive and factory based on the original plugin developed by Marco Rinck. It has the following dependencies:

You can also use this repository without bootstrap by simply styling the alert classes yourself. The following dependencies are optional:

  • Angular Translate (latest version) adds support for translating the notifications with angular.
  • Angular Animations (latest version) adds support for transitions and animations.

Installation

The best way is to install angular-growl-2 is with bower. This includes the javascript file and the css file.

bower install angular-growl-v2

You can also download the complete repo and include the files manually in your project

<html>
  <head>
    <link href="bootstrap.min.css" rel="stylesheet">
    <script src="angular.min.js"></script>

    <link href="angular-growl.css" rel="stylesheet">
    <script src="angular-growl.js"></script>
  </head>
</html>

Angular-growl is based on its own AngularJS module, you have to add it to the dependency list when creating your application module:

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

Finally you have to include the growl directive somewhere in your HTML:

<body>
  <div growl></div>
</body>

To get started, inject the growl factory in your controller and call one of the 4 basic functions that the factory provides. The following 4 types of messages are available:

  • Warning
  • Info
  • Danger
  • Success

Place an empty div in your HTML markup with the growl directive. The growl notifications will be rendered inside the empty div. For growl like notification the location of the div in the DOM does not matter.

See the Pen Angular Growl by Jan Stevens (@JanStevens) on CodePen.

Accept only unique messages as a new message. If a message is already displayed (text, severity and title are the same) then this message will not be added to the displayed message list.

Set to false, to always display all messages regardless if they are already displayed or not. Uniqueness of messages is determined by the message text, severity and title.

app.config(['growlProvider', function(growlProvider) {
  growlProvider.onlyUniqueMessages(false);
}]);

See the Pen Angular Growl Unique Messages by Jan Stevens (@JanStevens) on CodePen.

By default new messages are added to the bottom of the growl stack. This property allows to reverse the default order. When set to true new messages will be placed at the top of the stack (instead of the default bottom).

app.config(['growlProvider', function(growlProvider) {
  growlProvider.globalReversedOrder(true);
}]);

See the Pen Angular Growl Reverse Messages by Jan Stevens (@JanStevens) on CodePen.

The time to live of a messages can be controlled globally, globally per severity or per message. When the timer is over the message will be removed. Following example sets a global time to live for all the messages:

app.config(['growlProvider', function(growlProvider) {
  growlProvider.globalTimeToLive(5000);
}]);

This sets a global timeout of 5 seconds after which every notification will be closed. It's also possible to provide the TTL based on the severity of the message.

app.config(['growlProvider', function(growlProvider) {
  growlProvider.globalTimeToLive({success: 1000, error: 2000, warning: 3000, info: 4000});
}]);

The TTL can also be overwritten per message, this will ignore the globally set TTL

app.controller("demoCtrl", ['$scope', 'growl', function($scope, growl) {
  $scope.addSpecialWarnMessage = function() {
    growl.warning("Override global ttl setting", {ttl: 10000});
  }
}]);

Finally you can disable the closing of individual messages by setting their TTL to -1

app.controller("demoCtrl", ['$scope', 'growl', function($scope, growl) {
  $scope.addSpecialWarnMessage = function() {
    growl.warning("this will not be closed automatically", {ttl: -1});
  }
}]);
Important: Clicking on a growl message will disable the TTL. This is handy for longer messages and allows the user to completely read it. Dismissing the message is still possible by clicking on it again.

See the Pen Angular Growl Reverse Messages by Jan Stevens (@JanStevens) on CodePen.

Messages will have a countdown timer representing the TTL. The countdown timer can be disabled on a global and per message basis.

app.config(['growlProvider', function(growlProvider) {
  growlProvider.globalDisableCountDown(true);
}]);
app.controller("demoCtrl", ['$scope', 'growl', function($scope, growl) {
  $scope.addSpecialWarnMessage = function() {
    growl.warning("Does not have count down timer", {disableCountDown: true});
  }
}]);

See the Pen Angular Growl Reverse Messages by Jan Stevens (@JanStevens) on CodePen.

Accept only X messages inside the growl container. Automatically flush collection to limited count on each new message and so overwriting growl messages. Useful when growl is handling messages corresponding to specified element (for example input box inside form), and you need to show specified number of messages (for example 1). The setting is set on the growl div container.

Important: New messages will always overwrite old once, even when the user has disabled the TTL (by clicking on the message).

<body>
  <div growl limit-messages="1"></div>
</body>

See the Pen Angular Growl Reverse Messages by Jan Stevens (@JanStevens) on CodePen.

Two callbacks are triggered during a growl notification life-cycle. When it is displayed an onopen callback is trigger. When the message closes an onclose callback is trigger. Callbacks are functions provided in the config of a message.

app.controller("demoCtrl", ['$scope', 'growl', function($scope, growl) {
  $scope.addSpecialWarnMessage = function() {
    growl.warning("Warning MEssage", {
      onclose: function() {
        console.log('The message is closed!');
      },
      onopen: function() {
        console.log('The message is open!');
      }
    });
  }
}]);

See the Pen Angular Growl Reverse Messages by Jan Stevens (@JanStevens) on CodePen.

Starting from v0.6, HTML can always be included in the message text (not the title!). It uses the $sce service from angular to mark the HTML as trusted.

app.controller("demoCtrl", ['$scope', 'growl', function($scope, growl) {
  $scope.addSpecialWarnMessage = function() {
    growl.warning("<strong>This is a HTML message</strong>");
  }
}]);

See the Pen Angular Growl Reverse Messages by Jan Stevens (@JanStevens) on CodePen.

The icons are hardcoded as base64 strings in the css file. The original images can be found in the src/images folder of this repository. The icons can be disabled on a global and per message basis.

app.config(['growlProvider', function(growlProvider) {
  growlProvider.globalDisableIcons(true);
}]);
app.controller("demoCtrl", ['$scope', 'growl', function($scope, growl) {
  $scope.addSpecialWarnMessage = function() {
    growl.warning("<strong>This is a message without an icon", {disableIcons: true});
  }
}]);

See the Pen Angular Growl Reverse Messages by Jan Stevens (@JanStevens) on CodePen.

The close button allows the user to close the message. The button can be disabled on a global and per message basis.

app.config(['growlProvider', function(growlProvider) {
  growlProvider.globalDisableCloseButton(true);
}]);
app.controller("demoCtrl", ['$scope', 'growl', function($scope, growl) {
  $scope.addSpecialWarnMessage = function() {
    growl.warning("<strong>This is a message without an icon", {disableCloseButton: true});
  }
}]);

See the Pen Angular Growl Reverse Messages by Jan Stevens (@JanStevens) on CodePen.

Controls the location of all the messages. The default location is top-right like in most notification systems. Changing the property can only be done on a global basis, allowed options are:

  • top-left
  • top-right
  • bottom-left
  • bottom-right
  • top-center
  • bottom-center
app.config(['growlProvider', function(growlProvider) {
  growlProvider.globalPosition('bottom-center');
}]);

See the Pen Angular Growl Reverse Messages by Jan Stevens (@JanStevens) on CodePen.

This allows to display the growl messages inline instead of floating in the top-right corner. Multiple inline growl containers can be used on a single page (see reference id for more information). The property can be set on a global basis or overwrite it per directive.

app.config(['growlProvider', function(growlProvider) {
  growlProvider.globalInlineMessages(true);
}]);
<form>
  <div growl inline="true"></div>
  <label>Name:<label><input type="text" name="name" />
</form>

See the Pen Angular Growl Reverse Messages by Jan Stevens (@JanStevens) on CodePen.

When using inline growl notifications, it is possible to have multiple growl directives. For this reason it is possible to define a referenceId on the directive. When sending a message give it the same referenceId as the one in the directive configuration.

app.controller("demoCtrl", ['$scope', 'growl', function($scope, growl) {
  $scope.sendToGrowl = function() {
    growl.warning("This is only send to growl directive with referenceId = 1", {referenceId: 1});
    }
}]);
<form>
  <div growl inline="true" reference="1"></div>
  <label>Name:<label><input type="text" name="name" />
</form>

See the Pen Angular Growl Reverse Messages by Jan Stevens (@JanStevens) on CodePen.

Beginning with angularJS 1.2 growl messages can be automatically animated with CSS animations when adding and/or closing them. All you have to do is load the angular-animate.js provided by angularJS and add ngAnimate to your applications dependency list.

<html>
  <head>
    <link href="bootstrap.min.css" rel="stylesheet">
    <script src="angular.min.js"></script>
    <script src="angular-animate.min.js"></script>

    <link href="angular-growl.css" rel="stylesheet">
      <script src="angular-growl.js"></script>
  </head>
</html>
var app = angular.module('myApp', ['angular-growl', 'ngAnimate']);

Angular Growl comes with a pre-defined animation of 0.5s to opacity. To configure the animations change the .growl-container > .growl-item.* classes in the css file to your preference. For example changing the animation length to 1s instead of 0.5s default.

.growl-container > .growl-item.ng-enter,
.growl-container > .growl-item.ng-leave {
  -webkit-transition:1s linear all;
  -moz-transition:1s linear all;
  -o-transition:1s linear all;
  transition:1s linear all;
}

Basically you can style your animations just as you like if ngAnimate can pick it up automatically. See the ngAnimate docs for more info.

When doing $http requests, you can configure angular-growl to look automatically for messages in $http responses, so your business logic on the server is able to send messages/notifications to the client and you can display them automagically:

app.config(['growlProvider', '$httpProvider', function(growlProvider, $httpProvider) {
  $httpProvider.interceptors.push(growlProvider.serverMessagesInterceptor);
}]);

This adds a pre-defined angularJS HTTP interceptor that is called on every HTTP request and looks if response contains messages. Interceptor looks in response for a messages array of objects with text, title and severity key. This is an example response which results in 3 growl messages:

{
  "someOtherData": {...},
  "messages": [
    {"text":"this is a server message", "severity": "warn"},
    {"text":"this is another server message", "severity": "info"},
    {"text":"and another", "severity": "error", "title" : "Server side errors!"}
  ]
}

The default message, text, severity and title key can be configured

app.config(["growlProvider", "$httpProvider", function(growlProvider, $httpProvider) {
    growlProvider.messagesKey("my-messages");
    growlProvider.messageTextKey("message-text");
    growlProvider.messageTitleKey("message-title");
    growlProvider.messageSeverityKey("severity-level");
    $httpProvider.interceptors.push(growlProvider.serverMessagesInterceptor);
}]);

It's also possible to insert variables from the server response. The following json response will place the first name value in place of the key.

{
  "messages": [
    {"text":" this is a server message", "severity": "warning",  "variables": {"field":"first name"}}
  ]
}

See the Pen Angular Growl Reverse Messages by Jan Stevens (@JanStevens) on CodePen.

It is possible to replace the template of the growlDirective. The template is stored in the $templateCache and can be overwritten by defining your own template with id templates/growl/growl.html

<script type="text/ng-template" id="templates/growl/growl.html">
// your template here
</script>

Important: Omitting one of the ng-show or ng-click directives in the template can brake angular-growl.

A safer option to alter the view of the growl notifications is to change the css. The following classes are defined:

  • growl-container: the main div that holds all the growl messages for the directive
  • growl-item: a individual growl notification item
  • growl-title: the title of the notification
  • growl-message: the message of the notification

The icons used in the notification are included in the css as base64 strings. The original images (white and colored) can be found in the src/images folder.