JQuery Plugin: imBannerRotater

Note: The imBannerRotater has been replaced with gpImageRotate.
I created simple JQuery plugin that rotates images on a page. Actually, there are three modes: random, rotate, carousel, and portfolio. In the default mode, random, the plugin will display a randomly selected image. In the rotate mode, the plugin will rotate images on a page (fading in/out). In this mode, you can select the speed of the rotation. In the carousel mode, the images will move to the left in a carousel effect. I recently added a portfolio mode that using the same carousel effect, but the images are displayed differently. The image data can be retrieved ajaxally (json or a comma separated list). If the data is Json, a url can be added for each image. You can also set the image title and set whether the url will appear in a separate window (target = ‘_blank’) or in the same window (target = ‘_self’).

Plugin Options

Setting the imBannerRotater is simple:

mode: ‘random’, ‘rotate’, ‘carousel’, or ‘portfolio’. Randomly display images on a page, fade images in and out, or slide images to the left. The default mode is ‘random’.

image_url: This option really should be named data_url. This the location of the file list that will be retrieved ajaxally.

return_type: ‘list’ or ‘json’. This option tells the plugin whether the data retrieved via the image_url is a comma separated list or a json object. The defualt is ‘list’.

images: This option can be used instead of the image_url option (return_type = list). Just enter a comma separated list of image names.

base_path: Your file list can contain the full path of each image. If your list contains the file name only, you can use the base_path option to prefix all of the image in the list.

data_map: This option must be used if your return_type = json. This tells the plugin where to find the image name in the json object. You can also specify a url for each image and the url_target. The default for the url_target is ‘_blank’. The format for the data_map:

?View Code JAVASCRIPT
{image_name: 'the image name field', url_name: 'the url for the image', url_target: '_blank'}
 
//if no url
{image_name: 'the image name field'}

speed: This option is used with the mode = rotate. This is the speed in which each image fades in/out. The default is 1500. It will accept any value that is accepted by JQuery’s fadein effect.

Setting Up Plugin

To setup the plugin, first you need to load jquery and the imBannerRotater script:

<script src="js/jquery/jquery-1.4.min.js" type="text/javascript"></script>
<script src="js/jquery/jquery.imBannerRotater-1.1.js" type="text/javascript"></script>

Styling The Plugin

#cast {
	float:left;
	margin-left:40px;
	margin-top:20px;
}
IMG {
	border:none;
}

Random Mode

?View Code JAVASCRIPT
$(document).ready(function(){
	$("#cast").imBannerRotater({
		image_url: 'random.php',
		base_path: 'images/'
	});
});

In the example above, the ‘cast’ id selector is the container for the images. The base_path option tells the plugin to look for the images in the images directory. No mode is set, so the default is random. The return_type is not set. The default is list, so the plugin will be looking for a comma separated file list. The random.php will look similar to:

echo 'joneil.jpg,scarter.jpg,djackson.jpg,tealc.jpg,cmitchell.jpg,vala.jpg';

Rotate Mode

In this next example, I will load a json object. Notice image_name and url_name of the data_map option. Also notice, that I have set the mode to rotate.

?View Code JAVASCRIPT
$(document).ready(function(){
	$("#cast").imBannerRotater({
	    mode: 'rotate',
	    return_type: 'json',
	    image_url: 'rotate.php',
	    base_path: 'images/',
	    data_map: {image_name: 'name', url_name: 'url'}
	});
});

The rotate.php file contains a json object:

$json = '[{"name": "joneil.jpg", "url": "http://www.imdb.com/character/ch0005968/"},{"name": "scarter.jpg", "url": "http://www.imdb.com/character/ch0005974/"},';
	$json .= '{"name": "djackson.jpg", "url": "http://www.imdb.com/character/ch0005966/"},{"name": "tealc.jpg", "url": "http://www.imdb.com/character/ch0005979/"},';
	$json .= '{"name": "cmitchell.jpg", "url": "http://www.imdb.com/character/ch0005982/"},{"name": "vala.jpg", "url": "http://www.imdb.com/character/ch0005977/"}]';
	echo $json;

Rotate Interval

When in rotate mode, you can also set the interval option. The interval option is the amount of time (in milliseconds) that you want to wait before the next image rotates. When setting the interval option, the fade in/out will occur simultaneously.

?View Code JAVASCRIPT
$(document).ready(function(){
	$("#cast").imBannerRotater({
	    mode: 'rotate',
            interval: 5000,
	    return_type: 'json',
	    image_url: 'rotate.php',
	    base_path: 'images/',
	    data_map: {image_name: 'name', url_name: 'url'}
	});
});

Carousel Option

When using the carousel option, the images move to the left at a set interval. The CSS is a bit different:

#cast {
	float:left;
	overflow:hidden;
	margin-top: 40px;
	margin-left: 20px;
	width:500px;
	height:100px;	
}
#cast ul {
	margin:0;
	padding:0;
	list-style:none;
	position:relative;
	left:0;
	width:1200px;
}
#cast ul li {
	float:left;
	margin-left:10px;
	height:100px;
	display:inline;
}
IMG {
	border:none;
}

The main styling to remember is that the main container has the attribute overflow:hidden. Also, the width of the ul must be set to a value that is large enough to ensure that all images remain on the same row. If this value is set too low, then the the images will wrap.

?View Code JAVASCRIPT
$(document).ready(function(){
	$("#cast").imBannerRotater({
	    mode: 'carousel',
            interval: 5000,
	    return_type: 'json',
	    image_url: 'rotate.php',
	    base_path: 'images/',
	    data_map: {image_name: 'name', url_name: 'url'}
	});
});

Image Title

?View Code JAVASCRIPT
$(document).ready(function(){
	$("#cast").imBannerRotater({
	    mode: 'carousel',
            interval: 5000,
	    return_type: 'json',
	    image_url: 'rotate.php',
	    base_path: 'images/',
	    data_map: {image_name: 'name', url_name: 'url', image_title: 'image_title'}
	});
});
$json = '[{"name": "joneil.jpg", "url": "http://www.imdb.com/character/ch0005968/", "image_title": "Jack O\'neil"},{"name": "scarter.jpg", "url": "http://www.imdb.com/character/ch0005974/", "image_title": "Samantha Carter"},';
$json .= '{"name": "djackson.jpg", "url": "http://www.imdb.com/character/ch0005966/", "image_title": "Daniel Jackson"},{"name": "ghammond.jpg", "url": "http://www.imdb.com/character/ch0006003/", "image_title": "George Hammond"},{"name": "tealc.jpg", "url": "http://www.imdb.com/character/ch0005979/", "image_title": "Teal\'c"},';
$json .= '{"name": "cmitchell.jpg", "url": "http://www.imdb.com/character/ch0005982/", "image_title": "Cameron Mitchell"},{"name": "vala.jpg", "url": "http://www.imdb.com/character/ch0005977/", "image_title": "Vala Mal Doran"}]';
echo $json;

By default, when a user moves their mouse over an image, the image name will be displayed. You have the option to display whatever text you want by adding the value to the data_map option.

Portfolio Option

I added a portfolio option in version 1.1 of the imBannerRotater. This option using the same effect as the carousel option, but a single image is displayed at a time.

Just like the carousel option, an interval can be set. Unlike the carousel option, the portfolio has navigation arrows displayed on each side. You can alternatively turn off the display of the side navigation by setting the show_side_nav option to false:

?View Code JAVASCRIPT
$(document).ready(function(){
	$("#imImageRotateCntnr").imBannerRotater({
		mode: 'portfolio',
		interval: 8000,
		return_type: 'json',
		data_map: {
			image_name: 'name',
			url_name: 'url',
			image_title: 'image_title',
			image_desc: 'image_desc'
		},
		image_url: "portfolio.php",
		base_path: "images/bobmarley/",
                show_side_nav: false
	});
});

Image Description

Notice that I have added another option to the data_map (image_desc). Use this to return an image description that will be displayed below the image title. Both the image title and description are children of the same container. You have 3 options for the display of the container:

  • onhover – the container will be displayed when the user mouses over the image (the default)
  • onload – the container will be displayed with the image
  • never – do not display the title and description

Use the show_desc option to change it’s display value:

?View Code JAVASCRIPT
$(document).ready(function(){
	$("#imImageRotateCntnr").imBannerRotater({
		mode: 'portfolio',
		interval: 8000,
		return_type: 'json',
		data_map: {
			image_name: 'name',
			url_name: 'url',
			image_title: 'image_title',
			image_desc: 'image_desc'
		},
		image_url: "portfolio.php",
		base_path: "images/bobmarley/",
                show_desc: 'onload'
	});
});

Vertical Navigation

The portfolio will also display vertical navigation. The imBannerRotater will display a small circle for every image loaded (aligned vertically). The circle associated with the relevant image will have a different color than the other circles. Again, you have 3 options for the display of the vertical navigation:

  • top – displays above the image (the default)
  • bottom – displays below the image
  • no (or ”) – will not create the vertical navigation

Use the show_vert_nav option to change the vertical navigation display:

?View Code JAVASCRIPT
$(document).ready(function(){
	$("#imImageRotateCntnr").imBannerRotater({
		mode: 'portfolio',
		interval: 8000,
		return_type: 'json',
		data_map: {
			image_name: 'name',
			url_name: 'url',
			image_title: 'image_title',
			image_desc: 'image_desc'
		},
		image_url: "portfolio.php",
		base_path: "images/bobmarley/",
                show_vert_nav: 'bottom'
	});
});

Easing Option

I also added an easing option both the Portfolio and Carousel modes. I’m using the jquery.easing.js plugin. The default easing value is easeOutElastic. You can view the other easing options on the developers site.

?View Code JAVASCRIPT
$(document).ready(function(){
	$("#imImageRotateCntnr").imBannerRotater({
		mode: 'portfolio',
		interval: 8000,
		return_type: 'json',
		data_map: {
			image_name: 'name',
			url_name: 'url',
			image_title: 'image_title',
			image_desc: 'image_desc'
		},
		image_url: "portfolio.php",
		base_path: "images/bobmarley/",
                easing: 'easeOutCubic'
	});
});

Note: I have bundled the jquery.easing.js plugin the imBannerRotater plugin.

<script src="js/jquery/jquery-1.4.min.js" type="text/javascript"></script>
<script src="js/jquery/jquery.easing.js" type="text/javascript"></script>
<script src="js/jquery/jquery.imBannerRotater-1.1.js" type="text/javascript"></script>

Styling Portfolio Mode

The CSS for the portfolio mode is a lot more involved than the other modes. I have listed the styles below with comments for each:

/* container for all modes. When used with Portfolio mode, width should be  */
/* the width of the images + (width of imImageRotate-Side-Nav  * 2) */
/* When used with Carousel mode, width should wide enough to display multiple images */
/* All other modes, width should width of images */ 
#gpImageRotateCntnr {
	float:left;
	width:526px;
	margin: 5px 0 30px 40px;
}
.imImageRoate-Vert-Nav {
	float:left;
	width:100%;
	height:15px;
	margin-bottom:10px;
	display:none;
}
.imImageRoate-Vert-Nav ul {
	float: right;
	list-style:none;
	margin:0;
	padding:0;
	margin-top:5px;
	margin-right:30px;
}
 
.imImageRoate-Vert-Nav ul li, .imImageRoate-Vert-Nav ul li.selected {
	float:left;
	display:block;
	background: url('images/dot-nav-blue2.png') no-repeat;
	cursor:pointer;
	height:9px;
	width:9px;
	margin-left:5px;
}
 
.imImageRoate-Vert-Nav ul li.selected  {
	background: url('images/dot-nav-blue1.png') no-repeat;
}
 
/* height of the images, width should be the same or larger than the navigation buttons */
.imImageRotate-Side-Nav {
	float:left;
	width:30px;
	height:373px;
	text-align:center;
	display:none;
}
.imImageRotate-PrevBtn, .imImageRotate-NextBtn {
	float:left;
	width:27px;
	height:40px;
	cursor:pointer;
	background:url('images/navPrev.png') no-repeat;
	margin-top:320px;
}
.imImageRotate-NextBtn {
	background: url('images/navNext.png') no-repeat;
}
/* height and width of the images */
.imImageRotate-SlideCntnr {
	float:left;
	width:466px;
	height:373px;
	overflow:hidden;
	margin:0;
	padding:0;
}
/* width should be a large number. Will vary by image width and number of images */
.imImageRotate-Slider {
	position:relative;
	left:0;
	top:0;
	width:5000px;
	margin:0;
	padding:0;
}
/* image container - should be height and width of the images */
.imImageRotate-DisplayCntnr {
	float:left;
	margin:0;
	padding:0;
	width:466px;
	height:373px;
	font-family:Arial, Helvetica, sans-serif;
}
/* image title and description container */
.imImageRotate-TextCntnr {
	position:relative;
	top:-120px;
	background: rgba(85, 85, 85, 0.7);
	height:120px;
	display:none;
}
/* image title */
.imImageRotate-TextCntnr h2 {
	color:#fff;
	font: 16px bold Arial, Helvetica, sans-serif; 
	text-align:center;
	line-height:24px;
}
/* image description */
.imImageRotate-TextCntnr p {
	color:#fff;
	font: 11px Arial, Helvetica, sans-serif;
	margin:7px; 
}

I have bundled a side navigation image and 3-4 vertical navigation images (various colors).

Update Version 2.0 – 12-29-2011

I just updated the plugin to version 2.0. One of the primary changes is the portfolio, carousel, and steps(new) modes no longer scroll back to the beginning so the image rotation has more of a continuouse effect.

Steps Mode

I added steps that displays the images with a stair-step effect.

?View Code JAVASCRIPT
$(document).ready(function(){
	$("#imImageRotateCntnr").imBannerRotater({
		mode: 'steps',
		steps_large_height: '400',
		steps_small_height: '100',
		interval: 8000,
		speed: 2000,
		easing: '',
		return_type: 'json',
		data_map: {
			image_name: 'name',
			url_name: 'url',
			image_title: 'image_title',
			image_desc: 'image_desc'
		},
		image_url: 'imbannerrotater/portfolio.php',
		base_path: 'imbannerrotater/bobmarley/'
	});
});

Set the steps_large_height and steps_small_height options to set the size of the images.

Existing Images

The plugin now has the ability to create the various effects with existing images on a page. Set the image_url option to self. The plugin will then look for all li tags within the main container.

?View Code JAVASCRIPT
$(document).ready(function(){
	$("#imImageRotateCntnr").imBannerRotater({
		mode: 'portfolio',
		interval: 8000,
		speed: 2000,
		image_url: "self"
	});
});

To view a demo of the imBannerRotater plugin, go to: http://grasshopperpebbles.com/demos/.

Version 2 of the plugin can be downloaded from GitHub.

Previous versions can be downloaded from Google Code or JQuery Plugins.

Be Sociable, Share!

Checkout My New Site - T-shirts For Geeks