#angular-growl
growl like notifications for angularJS projects, using bootstrap alert classes
##Features
- growl like notifications like in MacOS X
- using standard bootstrap classes (alert, alert-info, alert-error, alert-success)
- global or per message configuration of a timeout when message will be automatically closed
- automatic translation of messages if angular-translate filter is present, you only have to provide keys as messages, angular-translate will translate them
- pre-defined $http-Interceptor to automatically handle $http responses for server-sent messages
- automatic CSS animations when adding/closing notifications (only when using >= angularJS 1.2)
- < 1 kB after GZIP
##Changelog
0.3.1 - 1st Oct 2013
- bugfix: translating of messages works again
- change: also set alert css classes introduced by bootstrap 3
0.3.0 - 26th Sept 2013
- adding css animations support via ngAnimate (for angularJS >= 1.2)
- ability to configure server message keys
0.2.0 - 22nd Sept 2013
- reworking, bugfixing and documenting handling of server sent messages/notifications
- externalizing css styles of growl class
- provide minified versions of js and css files in build folder
0.1.3 - 20th Sept 2013
- introducing ttl config option, fixes #2
##Installation
You can install angular-growl with bower:
bower install angular-growl
Alternatively you can download the files in the build folder manually and include them 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>As angular-growl is based on its own angularJS module, you have to alter your dependency list when creating your application module:
var app = angular.module('myApp', ['angular-growl']);Finally, you have to include the directive somewhere in your HTML like this:
<body>
<div growl></div>
</body>##Usage
Just let angular inject the growl Factory into your code and call the 4 functions that the factory provides accordingly:
app.controller("demoCtrl", ['$scope', 'growl', function($scope, growl) {
$scope.addSpecialWarnMessage = function() {
growl.addWarnMessage("This adds a warn message");
growl.addInfoMessage("This adds a info message");
growl.addSuccessMessage("This adds a success message");
growl.addErrorMessage("This adds a error message");
}
}]);If you wanted to be notified when the message either closes automatically or when the user closes the message, you can provide a callback function to be executed. This allows you to clear forms or provide any other specific logic that you wish to perform.
If angular-translate is present, its filter is automatically called for translating of messages, so you have to provide only the key:
app.controller("demoCtrl", ['$scope', 'growl', function($scope, growl) {
$scope.addSpecialWarnMessage = function() {
growl.addSuccessMessage("SAVE_SUCCESS_MESSAGE");
growl.addErrorMessage("VALIDATION_ERROR");
}
}]);##Configuration
###Automatic closing of notifications (timeout, ttl) Standard behaviour is, that all notifications need to be closed manually by the user.
However, you can configure a global timeout (TTL) after which notifications should be automatically closed. To do this, you have to configure this during config phase of angular bootstrap like this:
var app = angular.module('myApp', ['angular-growl']);
app.config(['growlProvider', function(growlProvider) {
growlProvider.globalTimeToLive(5000);
}]);This sets a global timeout of 5 seconds after which every notification will be closed.
You can override TTL generally for every single message if you want:
app.controller("demoCtrl", ['$scope', 'growl', function($scope, growl) {
$scope.addSpecialWarnMessage = function() {
growl.addWarnMessage("Override global ttl setting", {ttl: 10000});
}
}]);This sets a 10 second timeout, after which the notification will be automatically closed.
If you have set a global TTL, you can disable automatic closing of single notifications by setting their ttl to -1:
app.controller("demoCtrl", ['$scope', 'growl', function($scope, growl) {
$scope.addSpecialWarnMessage = function() {
growl.addWarnMessage("this will not be closed automatically even when a global ttl is set", {ttl: -1});
}
}]);###Animations
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']);That's it. The angular-growl.css comes with a pre-defined animation of 0.5s to opacity.
To configure the animations, just change the growl-item.* classes in the css file to your preference. F.i. to change length of animation from 0.5s to 1s do this:
.growl-item.ng-enter,
.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.
###Handling of server sent notifications
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:
var app = angular.module('myApp', ['angular-growl']);
app.config(['growlProvider', '$httpProvider', function(growlProvider, $httpProvider) {
$httpProvider.responseInterceptors.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" 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"}
]
}You can configure the keys, the interceptor is looking for like this:
var app = angular.module("demo", ["angular-growl"]);
app.config(["growlProvider", "$httpProvider", function(growlProvider, $httpProvider) {
growlProvider.messagesKey("my-messages");
growlProvider.messageTextKey("messagetext");
growlProvider.messageSeverityKey("severity-level");
$httpProvider.responseInterceptors.push(growlProvider.serverMessagesInterceptor);
}]);Server messages will be created with default TTL.