Introduction

Amaranjs yet another notification jQuery plugin.

Minimal Setup

Go to dist directory and copy all the folders to a new destination, which will be your project home.

It’s not required, but I recommend placing CSS files in <head> and JavaScript files and initialization code in the footer of your site (before the closing </body> tag).

<link rel="stylesheet" href="/css/amaran.min.css">

jQuery required for Amaran JS.If you already have jquery.js on your site, don’t include it a second time, or use jQuery.noConflict(); mode.

You can add jQuery via Google CDN

<script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>

So minimalistic setup look like this

<!DOCTYPE html>
<html>
<head>
    <title>My Web Page</title>
    <link rel="stylesheet" href="amaran/css/amaran.min.css">
</head>
<body>
    <p>My Content</p>
    <script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
    <script src="amaran/js/jquery.amaran.min.js"></script>
</body>
</html>

Recommended Setup

I recommend Font Awesome Icons and Open Sans for better-looking notifications. Especially for the default theme.

Just place these two CSS files inside your <head> section.

<link href="//netdna.bootstrapcdn.com/font-awesome/4.0.3/css/font-awesome.css" rel="stylesheet">
<link href='http://fonts.googleapis.com/css?family=Open+Sans:400,600' rel='stylesheet' type='text/css'>

So recommended setup should look like;

<!DOCTYPE html>
<html>
<head>
    <title>My Web Page</title>
    <link href="//netdna.bootstrapcdn.com/font-awesome/4.0.3/css/font-awesome.css" rel="stylesheet">
    <link href='http://fonts.googleapis.com/css?family=Open+Sans:400,600' rel='stylesheet' type='text/css'> 
    <link rel="stylesheet" href="amaran/css/amaran.min.css">
</head>
<body>
    <p>My Content</p>
    <script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
    <script src="amaran/js/jquery.amaran.min.js"></script>
</body>
</html>

CDN Usage

You can find AmaranJS at jsDelivr

CSS

<link rel="stylesheet" href="//cdn.jsdelivr.net/jquery.amaran/0.5.4/amaran.min.css">

jQuery Plugin

<script src="//cdn.jsdelivr.net/jquery.amaran/0.5.4/jquery.amaran.min.js"></script>

Basic Usage

We are ready to create our first example. Very very simple usage of Amaran JS.

First of all we must add our code inside jQuery document ready function $(function(){ });

$(function(){
    $.amaran({content:{'message':'My first example!'}});
}); 

If you add this code inside $(function(){ }); function it will automatically starts when page loads.

This code using the default theme.If you want to use default theme you don't have to specify theme option.

Let's create a notification with the awesome theme.

$.amaran({
    content:{
        title:'My first funcy example!',
        message:'1.4 GB',
        info:'my_birthday.mp4',
        icon:'fa fa-download'
    },
    theme:'awesome ok'
});

Lets see full example.

<!DOCTYPE html>
<html>
<head>
    <title>My Web Page</title>
    <link href="//netdna.bootstrapcdn.com/font-awesome/4.0.3/css/font-awesome.css" rel="stylesheet">
    <link href='http://fonts.googleapis.com/css?family=Open+Sans:400,600' rel='stylesheet' type='text/css'>
    <link rel="stylesheet" href="amaran/css/jquery.amaran.min.css">
    <link rel="stylesheet" href="amaran/css/themes/all-themes.css">
</head>
<body>
    <p>My Content</p>
    <script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
    <script src="amaran/js/jquery.amaran.js"></script>
    <script>
        $(function(){
            $.amaran({
                content:{
                    title:'Your Download is Ready!',
                    message:'1.4 GB',
                    info:'my_birthday.mp4',
                    icon:'fa fa-download'
                },
                theme:'default ok'
            });
        });
    </script>
</body>
</html>

Themes

AmaranJS has currently included 5 themes and you can extend with your own themes.You can check creating themes section.

Generally, themes have own specific setup so I'll try to cover each own them.

You can specify a theme by passing theme: '' option to Amaran JS object.

Awesome Theme

Awesome theme has 7 variations.

AmaranJS Awesome Variations

Sample Usage:

$.amaran({
    content:{
        title:'Your Download is Ready!',
        message:'1.4 GB',
        info:'my_birthday.mp4',
        icon:'fa fa-download'
    },
    theme:'awesome ok'
});

For awesome theme you can call theme and variation with theme awesome <VARIATION NAME> e.g : theme:'awesome ok' or theme:'awesome error'. We have 3 content options title, message, and info for the awesome theme .title represent the first line, message second line, and info representing the third line. With icon option, you can specify an icon. Awesome theme using Font Awesome icons. Icons list can be found in this http://fontawesome.io/icons/ here.

e.g For envelope icon just pass icons:'fa fa-envelope'

Creating your own variation

.amaran.awesome.<VARIATION NAME> p.bold{
    color:<COLOR CODE>;
}
.amaran.awesome.<VARIATION NAME> .icon {
    background-color:<COLOR CODE>;
    color:#fff;
}

Just change <VARIATION NAME> with your variation name and <COLOR CODE> with your color code and add in your main css file.

For example, we want to fancy pink color.

.amaran.awesome.pink p.bold{
    color:#D704DE;
}
.amaran.awesome.pink .icon {
    background-color:#D704DE;
    color:#fff;
}

AmaranJS Awesome Own Variations

User Theme

User theme has 4 variations.

AmaranJS User Theme

Sample Usage:

$.amaran({
    content:{
        img:'http://api.randomuser.me/0.2/portraits/men/36.jpg',
        user:'John Walker',
        message:'Lorem ipsum dolor sit amet, consectetur adipisicing elit. Cupiditate, ducimus?'
       },
    theme:'user green',
});

Colorful Theme

You can create flat style notifications with the colorful theme. You can easily change color.

AmaranJS Colorful Theme

Sample Usage:

$.amaran({
    content:{
        bgcolor:'#27ae60',
        color:'#fff',
        message:'Lorem ipsum dolor sit amet, consectetur adipisicing elit. Cupiditate, ducimus?'
       },
    theme:'colorful'
});

Tumblr Theme

This part not documented yet.

Options overview

Here are the default values of AmaranJS.

defaults = {
  position: "bottom right",
  content: " ",
  delay: 3000,
  sticky: false,
  stickyButton: false,
  inEffect: "fadeIn",
  outEffect: "fadeOut",
  theme: "default",
  themeTemplate: null,
  closeOnClick: true,
  closeButton: false,
  clearAll: false,
  cssanimationIn: false,
  cssanimationOut: false,
  resetTimeout: false,
  overlay: false,
  beforeStart: function() {},
  afterEnd: function() {},
  onClick: function() {}
};

Position

You can specify the position of notifications.All you have to do is just pass two-part string which first part is vertical (top or bottom) position and second part is horizontal (right or left) position.

For example, if I want to create notification at top left position;

position: "top left" // i guess its obvious

Delay

AmaranJS notifications set to disappear after 3 seconds if sticky option not sets true. So if you want to change default set value to milliseconds.

delay: 5500 // 5.5 second

Sticky

By default, AmaranJS set to disappear after 3 seconds.If you want to disable this feature for current notification just set the sticky option to true.

sticky:false // by default its false.    

StickyButton

You can set a sticky button for your notification. When user clicks on this button notification timer will stop/start.

inEffect

Basically one of the important options of AmaranJS.By default AmaranJS, notifications appear using fade effect but we have also 4 different built-in effects for AmaranJS and a lot of animate.css effects.For now, I will only cover AmaranJS effects.

slideLeft

Your notification will be slide to screen from the left of the screen even your notifications can be placed to the right of the screen.Just try it.

slideRight

Your notification will be slide to screen from the right of the screen.

slideRight

Your notification will be slide to screen from the right of the screen.

slideTop

Your notification will be slide to screen from the top of the screen.

  inEffect:'slideRight'

outEffect

This option for AmaranJS disappear effects. Similar to inEffect default is fade and 4 different slide effect.

slideLeft

Your notification will be slide from current position to the left of the screen.

slideRight

Your notification will be slide from current position to the right of the screen.

slideRight

Your notification will be slide from current position to the right of the screen.

slideTop

Your notification will be slide from current position to top of the screen.

Let's see an example.

  outEffect:'slideRight'

By default, each notification set disappear after 3 seconds(3000ms) and you can change this time with this option.

Default: delay:3000

  delay:10000

sticky

As I mentioned at delay option each notification set to disappear after 3 seconds.But you can set sticky:true for notification to remain on screen with this option.

Default: sticky:false

closeOnClick

By default, each notification set to be closed when you click on them.You can change this behavior with this option.You just need to set closeOnClick:false

Default: closeOnClick:true

closeButton

Notifications don't have a close button by default because you can close notifications by clicking on them.It is very useful when you disable close on click behavior.

Default: closeButton:false

clearAll

You can clear any notification on screen before your new notification appear.

Default: clearAll:false

cssanimationIn

Animate.css effect for appear animation.

cssanimationIn: 'swing'

cssanimationOut

Animate.css effect for disappear animation.

cssanimationIn: 'bounceOut'

beforeStart

Callback function that executes before notification shows up.

beforeStart: function(){
  alert("Hi");
}

afterEnd

Callback function that executes after notification disappears.

afterEnd: function(){
  alert("Hi");
}

themeTemplate

User templates.You can find more at creating themes section

Default themeTemplate:null

overlay

When you set true an overlay will show up.

Default overlay:false

resetTimeout

If you want notifications stay on screen when you hover notifications you can set this option true.It is very useful if you want to users copy a text or you have long text.