Documentation

READ THIS

I have found that many people are confused on how to use this plugin at first. This is because I do something very different when calling this plugin.

Usually when calling a plugin using jQuery you would call it like this:

$('body').growl({
	message: 'Hello World',
	type: 'danger'
});

DO NOT DO THAT

This is wrong when using this plugin. I have tried to make Bootstrap Growl as flexable I could think by including both options and settings. Below is an example showing all options and settings

$.growl({
	icon: 'glyphicon glyphicon-warning-sign',
	title: ' Bootstrap Growl ',
	message: 'Turning standard Bootstrap alerts into "Growl-like" notifications',
	url: 'https://github.com/mouse0270/bootstrap-growl'
},{
	element: 'body',
	type: "info",
	allow_dismiss: true,
	placement: {
		from: "top",
		align: "right"
	},
	offset: 20,
	spacing: 10,
	z_index: 1031,
	delay: 5000,
	timer: 1000,
	url_target: '_blank',
	mouse_over: false,
	animate: {
		enter: 'animated fadeInDown',
		exit: 'animated fadeOutUp'
	},
	icon_type: 'class',
	template: '<div data-growl="container" class="alert" role="alert">
		<button type="button" class="close" data-growl="dismiss">
			<span aria-hidden="true">×</span>
			<span class="sr-only">Close</span>
		</button>
		<span data-growl="icon"></span>
		<span data-growl="title"></span>
		<span data-growl="message"></span>
		<a href="#" data-growl="url"></a>
	</div>'
});

What if I just want to have a message?

That is fine, and really simple actually. Lets says I wanted to create a growl that was meant to inform the user the a script is saving and not to leave the page? Look at the example below.

$.growl('<strong>SAVING:</strong> Do not close this page', {
	type: 'danger'
});

Wait a second. You didn't assign `message`?

That is right. If you just want to pass a message and not you don't need to include anything else. If you want to pass a message and title all you have to include is a message and title.

$.growl({
	title: '<strong>SAVING:</strong> ',
	message: 'Do not close this page'
},{
	type: 'danger'
});

Options

Name	Type	Required	Description
message	string	`Yes`	This is the message that will be displayed within the growl notification.
icon	class \| src	`No`	This is the icon that will be displayed within the growl notification. This icon can either be a class (Font Icon) or an image url. Please keep in mind if you wish to use a image url that you must set `icon_type` to `img` in the options.
title	string	`No`	This is the title that will be displayed within the growl notification. Please keep in mind unless you style the `[data-growl="title"]` in css this will look identical to the `message`.
url	Web Address	`No`	If this value is set it will make the entire growl (except the close button) a clickable area. If the user clicks on this area it will take them to the url specified here.

Settings

Name	Type	Default	Description
element	string	`body`	Appends the growl to a specific element. If the element is set to anything other than the `body` of a document it switches from a `position: fixed` to `position: absolute`.
type	string	`info`	Defines the style of the growl using bootstraps native alert styles. Please keep in mind that when the growl in generated the `type` gets prefixed with `alert-`. When using native alert styles this will not be an issue, but if you create a new style such as `pink` when setting up the css you have to use the class `alert-pink`.
allow_dismiss	boolean	`true`	If this value is set to `false` it will hide the `data-grow="dismiss"` element. Please keep in mind if you modify the `template` option and do not include a `data-growl="dismiss"` element even with this set to `true` there will be no element for a user to click to close the growl.
placement.from	string	`top`	This controls where if the growl will be placed at the `top` or `bottom` of your element.
placement.align	string	`right`	This controls if the growl will be placed in the `left`, `center` or `right` side of the element.
offset	integer	`20`	This adds a padding in `pixels` between the element and the growl creating a space between their edges.
offset.x	integer	`20`	This adds a padding on the `x` axis in `pixels` between the element and the growl creating a space between their edges.
offset.y	integer	`20`	This adds a padding on the `y` axis in `pixels` between the element and the growl creating a space between their edges.
spacing	integer	`10`	This adds a padding in `pixels` between growls with the same placement creating a space between their edges.
z_index	integer	`1031`	Pretty simple, this sets the css property `z-index` for the growl. You may have to raise this number if you have other elements overlaping the growl.
delay	integer	`5000`	If `delay` is set higher than `0` then the growl will auto-close after the delay period is up. Please keep in mind that `delay` uses milliseconds so `5000` is `5 seconds`.
timer	integer	`1000`	This is the amount of milliseconds removed from the growl at every `timer`milliseconds. So to make that a little less confusing every `1000 milliseconds` there will be `1000 milliseconds` removed from the remaining time of the growl delay. If this is set higher then `delay` the growl will not be removed until `timer` has run out.
url_target	string	`_blank`	This sets the target of the url for a growl. please check HTML <a> target Attribute to learn more about these options.
mouse_over	string \| false	`false`	By default this does nothing. If you set this option to `pause` it will pause the timer on the growl delay. Since version 2.0.0 the timer will not reset it will continue from it's last tick.
animate.enter	string	`animated fadeInDown`	This will control the animation used to bring the generate the growl on screen. Since version 2.0.0 all animations are controlled using `css`. This plugin is not com packaged with any animations. Please use Animate.css by daneden or you can always write your own css animations.
animate.exit	string	`animated fadeOutUp`	This will control the animation used when the growl is removed from the screen. Since version 2.0.0 all animations are controlled using `css`. This plugin is not come packaged with any animations. Please use Animate.css by daneden or you can always write your own css animations.
onShow	function	`null`	This event fires immediately when the `show` instance method is called.
onShown	function	`null`	This event is fired when the modal has been made visible to the user (will wait for CSS transitions to complete).
onHide	function	`null`	This event is fired immediately when the `hide` instance method has been called.
onHidden	function	`null`	This event is fired when the modal has finished being hidden from the user (will wait for CSS transitions to complete).
icon_type	string	`class`	This is used to let the plugin know if you are using an `icon font` for images or if you are using `image`. If this setting is not set to `class` it will assume you are using an `img`. Please keep in mind if you are using an `image` you to set `icon` to the `src` of the `image`.
template	string	*code below*	Since version 2.0.0 the template option has been revamped in hopes of giving users more control over the layout. Please find the code for the default template below.

Default Template Setup

Bootrstrap growl now uses data attributes (data-growl) to place content with in the growl template.

container: Container of growl plugin
dismiss: Element used to allow user to manually close growl
icon: Either has a class for an icon image or will generate an img tag
title: Element that the growl plugin will insert title
message: Element that the growl plugin will insert message
url: Element will have href set if a url is passed.

<div data-growl="container" class="alert" role="alert">
	<button type="button" class="close" data-growl="dismiss">
		<span aria-hidden="true">×</span>
		<span class="sr-only">Close</span>
	</button>
	<span data-growl="icon"></span>
	<span data-growl="title"></span>
	<span data-growl="message"></span>
	<a href="#" data-growl="url"></a>
</div>

Important Information about icon's

If you decided to use an image instead of a font-icon you do not need to update the template. Just pass your src of the image in place of icon and make sure to set icon_type to img in the settings. The plugin will automatically create a img tag for you.

What if I want to change the template to use an img tag for the data-growl="icon" tag?

No worries, go ahead. Once again just make sure you change icon_type to img in the settings. The script will check to see if the data-growl="icon" is an img tag. If it is, it will just assign the src of the tag, otherwise it will create an img tag and use that instead.

Methods

Since version 2.0.0 there has been the addition of methods. To use a method you have to assign the growl to a variable when it is created. Take a look at the example below

var growl = $.growl('<strong>SAVING:</strong> Do not close this page', {
	type: 'danger'
});

.close();

You can programmatically close a growl using javascript

growl.close();

.update(command, update);

You can change the icon, title, message, url or type by calling the .update(); method in javascript.

growl.update('icon', 'fa fa-check');
growl.update('title', '<strong>SAVED:</strong> ');
growl.update('message', 'Save has completed');
growl.update('type', 'success');

Setting Defaults

Since version 2.0.0 the settings can be set globally to allow you to set them once and then never worry about them again.

To set the default settings all you have to do is pass false for the message and then the settings you want to be set.

$.growl(false, {
	type: 'pink',
	mouse_over: "pause"
});

Closing All Growls

Since version 2.0.0 you are now able to close all currently open growls by calling the code below.

$.growl(false, {
	command: 'closeAll'
});

Let's say you have growls in both the top left and top right and you want to just close the growls on the top left you can use the code below.

You can use the following options top-left, top-center, top-right, bottom-left, bottom-center or bottom-right.

$.growl(false, {
	command: 'closeAll',
	position: 'top-left'
});

Examples

Basic Bootstrap Growl

One of the simpliest implementations.

Create Growl

$.growl("Hello World");

Passing in a title

On of the great things about Bootstrap Growl is that you can easily include a title.

Create Growl

$.growl({
	title: "Welcome: ",
	message: "This plugin has been provided to you by Robert McIntosh aka mouse0270"
});

You can always pass in HTML if you would like to add a little extra flair to your growl.

Create Growl

$.growl({
	title: "<strong>Welcome:</strong> ",
	message: "This plugin has been provided to you by Robert McIntosh aka mouse0270"
});

Create Growl

$.growl({
	title: "<strong>Welcome:</strong> ",
	message: "This plugin has been provided to you by Robert McIntosh aka <a href=\"https://twitter.com/Mouse0270\" target=\"_blank\">@mouse0270</a>"
});

Passing in an icon

You can even pass in font icons! This should work with any font icons from Bootstrap, Font Awesome or Icomoon.

Create Growl

$.growl({
	icon: "glyphicon glyphicon-star",
	title: " ICONS: ",
	message: "Everyone loves font icons! Use them in your growl alert!"
});

Create Growl

$.growl({
	icon: "fa fa-paw",
	title: " Font Awesome: ",
	message: "This Growl uses font-awesomes paw icon, sorta looks like thr growl logo!"
});

Not a fan of font icons and would rather use images? No worries, Bootstrap Growl lets you toggle if you are using icons or images.

Create Growl

$.growl({
	icon: "img/growl_64x.png",
	message: " I am using an image."
},{
	icon_type: 'image'
});

Passing in a URL

One of the new features of Bootstrap growl v2+ is the ability to pass a url into the growl. When you do this it makes it so if the user clicks anywhere on the growl other than the dismiss button it will be a link you the url you passed it.

By default the growl will open in a new window/tab. You can change this by setting url_target to _self.

Create Growl

$.growl({
	message: "Check out my twitter account by clicking on this Growl!",
	url: "https://twitter.com/Mouse0270"
});

Create Growl

$.growl({
	message: "Check out my twitter account by clicking on this Growl! <strong>Warning: This growl will take you away from this screen</strong>",
	url: "https://twitter.com/Mouse0270"
},{
	url_target: '_self'
});

Using Offset Object

Since version 2+ you are able to use an x and y values in offset to set different paddings for the growl on the x and y axies.

If you use offset: 20 it will automatically set the x and y values to 20.

Set Growl Options

$.growl('Hello World', {
	offset: {
		x: 100,
		y: 20
	}
});

Changing the Growl Type

One of the requirements to use Bootstrap Growl is Bootstrap. Though this is true, it is also kinda a lie. The only reason this plugin requires Bootstrap is because it uses the styling of the alert class found in Bootstrap css. This means you can remove this requirement if you create your own alert style. It also means you can easily change the color of Growl notifications by passing in a type. By default Bootstrap growl uses type info

Create Growl

$.growl("I'll use Bootstrap Success Alert Styling!", {
	type: "success"
});

Create Growl

$.growl("I'll use Bootstrap Info Alert Styling!", {
	type: "info"
});

Create Growl

$.growl("I'll use Bootstrap Warning Alert Styling!", {
	type: "warning"
});

Create Growl

$.growl("I'll use Bootstrap Danger Alert Styling!", {
	type: "danger"
});

You can even create your own styles if you want. Check out the Growl and Pink styles in the Growl Builder.

.alert-growl {
	background-color: rgb(0, 0, 0);
	background-color: rgba(0, 0, 0, 0.8);
	border-color: rgb(255, 255, 255);
	border-width: 3px;
	color: rgb(255, 255, 255);
}

Create Growl

$.growl("I'll use custom <code>Growl</code> Styling!", {
	type: "growl"
});

.alert-pink {
	background-color: rgb(255, 223, 255);
	border-color: rgb(194, 97, 135);
	color: rgb(230, 96, 160);
}

Create Growl

$.growl("I'll use custom <code>Pink</code> Styling!", {
	type: "pink"
});

Setting Default Values

Since version 2+ you are able to set defaults so you do not need to pass in the same options very time.

To accomplish this all you have to do is pass false in for the options and any settings you would like in the settings area. This well set these as the default options from now on.

You can click on any of the other growls after setting the default and you will notice that they are now set to these new defaults.

Set Growl Options

$.growl(false, {
	type: 'pink'
});
$.growl('My default type is now set to pink');

Set Growl Options

$.growl(false, {
	allow_dismiss: false
});
$.growl('Close button is no longer available');

Set Growl Options

$.growl(false, {
	type: 'info'
});
$.growl('My default type is now set to info');

Set Growl Options

$.growl(false, {
	allow_dismiss: true
});
$.growl('Close button is available');

Animating Bootstrap Growls

One of the most powerful features in Bootstrap Growl 2+ is that you can easily animate how it enters and exits the screen using CSS (Please not that you can no longer animate the growls using jquery).

This does mean that for your growl you need to create your own css animations or you need to use a css file such a Animate.css.

Below are examples using Animate.css. The first one is using the defaults within the plugin.

Create Growl

$.growl("Enter: Fade In and Down<br/>Exit: Fade Out and Up");

Create Growl

$.growl("Enter: Fade In and Right<br/>Exit: Fade Out and Right", {
	animate: {
		enter: 'animated fadeInRight',
		exit: 'animated fadeOutRight'
	}								
});

Create Growl

$.growl("Enter: Bounce In from Top<br/>Exit: Bounce Up and Out", {
	animate: {
		enter: 'animated bounceInDown',
		exit: 'animated bounceOutUp'
	}								
});

Create Growl

$.growl("Enter: Bounce In<br/>Exit: Bounce Out", {
	animate: {
		enter: 'animated bounceIn',
		exit: 'animated bounceOut'
	}								
});

Create Growl

$.growl("Enter: Flip In on Y Axis<br/>Exit: Flip Out on X Axis", {
	animate: {
		enter: 'animated flipInY',
		exit: 'animated flipOutX'
	}								
});

Create Growl

$.growl("Enter: Light Speed In<br/>Exit: Light Speed Out", {
	animate: {
		enter: 'animated lightSpeedIn',
		exit: 'animated lightSpeedOut'
	}								
});

Create Growl

$.growl("Enter: Roll In<br/>Exit: Roll Out", {
	animate: {
		enter: 'animated rollIn',
		exit: 'animated rollOut'
	}								
});

Create Growl

$.growl("Enter: Zoom Down and In<br/>Exit: Zoom Up and Out", {
	animate: {
		enter: 'animated zoomInDown',
		exit: 'animated zoomOutUp'
	}								
});

Growl Builder

Information

Documentation

READ THIS

DO NOT DO THAT

What if I just want to have a message?

Wait a second. You didn't assign message?

Options

Settings

Default Template Setup

Important Information about icon's

Methods

.close();

.update(command, update);

Setting Defaults

Closing All Growls

Examples

Basic Bootstrap Growl

Passing in a title

Passing in an icon

Passing in a URL

Using Offset Object

Changing the Growl Type

Setting Default Values

Animating Bootstrap Growls

Wait a second. You didn't assign `message`?