Rotator.js | A jQuery rotating banner plugin

Rotator.js

A javascript banner rotator built on jQuery with extensive features and expandability.

Table of Contents

Overview

Learn what Rotator.js is all about and how you can use it.

What does it do?

Rotator.js will take a set of elements on a page and add rotation — or transitions — between them.

What are some good uses for Rotator.js?

Rotator.js is perfect for your homepage banner rotator, a simple image gallery with navigation, a news ticker, or anything else that needs a step navigation or auto rotation.

How hard is it to implement?

There's only a few main steps to take to get your rotator up and running.

Include jQuery and the Rotator.js file:

<script src="js/jquery.js" type="text/javascript"></script>
<script src="js/rotator.js" type="text/javascript"></script>

Write your rotator HTML:

<ul id="rotator" class="loading">
	<li class="slide"><img /></li>
	<li class="slide"><img /></li>
	<li class="slide"><img /></li>
	<li class="slide"><img /></li>
</ul>

Modify rotator styling to your liking:

/* default rotator styles */
#rotator { position: relative; width: 980px; height: 360px; overflow: hidden; background-color: white; margin: 0px; padding: 0px }
#rotator .slide { width: 980px; height: 360px; position: absolute; top: 0px; left: 0px; overflow: hidden; background: white; display: none; margin: 0px; padding: 0px }

/* default rotator nav styles */
#rotator-nav { display: block; position: absolute; bottom: 10px; right: 10px; z-index: 5000; background: white; opacity: .5; filter: alpha(opacity=40); padding: 4px; -moz-border-radius: 4px }
#rotator-nav:hover { opacity: 1; filter: alpha(opacity=100) }
#rotator-nav li { display: block; float: left; padding: 0px 2px }
#rotator-nav a { border: solid 1px #aaa; color: #aaa; font: normal 12px Arial; padding: 2px 3px; text-decoration: none; -moz-border-radius: 2px; outline: none }
#rotator-nav a:hover, #rotator-nav .current a { color: #0063B1; border-color: #0063B1 }
.loading { background: url(../images/ui/loading.gif) 50% 50% no-repeat }

Write the JavaScript to initiate the rotator:

jQuery(function ($) {
	window.rotator = $('#rotator').rotator({ /* config */ });
});

How can I customize the rotator?

Configuring your rotator to exactly how you want is the best part. We've made it so easy, Gary Busey could do it.

Here is a quick list of things you can configure:

Some Examples

Here is a list of common examples we have put together for you. If you find one you like, take a peak at the source to see how its done.

Config

Let's show you how to take full advantage of Rotator.js by setting the various config options available to you.

Useful for: Customizing Behavior, Automating More Tasks, Disabling Unwanted Features

Passing In Config Options

First, lets show you how to pass in a config object. Then we'll show you what's available.

Pass In A Config Object

Param
config Object

You will start by making a new config object, then pass it in on generation of your rotator.

jQuery(function($) {
	
	window.rotator = $('#rotator').rotator({ random: true, transition: 'fade', interval: 10000 });

	// or be easier to read

	var config = {
		random: true,
		transition: 'fade',
		interval: 10000 // 10 seconds
	};

	window.rotator = $('#rotator').rotator(config);

});

Available Config Options

Here are all of the config options available to you upon generation of your rotator.

config.first

Param
first Int
Default Value
1

The number of the slide to show first. In case you want to start at slide #3 and go from there.

config.random

Param
random Bool

Whether or not to start on a random slide.

Note: This option will override config.first.

config.reorderSlides

Param
reorderSlides Bool

If you chose to show slides in random order, this will reorder the slide nodes in the DOM so they match the shuffled order.

config.transition

Param
transition String
Default Value
'fade'

Choose which transition to use between slides. You can add your own transition if you'd like.

config.transitionDuration

Param
transitionDuration Int (in milliseconds)
Default Value
1000

The duration of the transition in milliseconds. 1000 == 1 second.

config.transitions

Param
transitions Object
Default Value
{ }

If you want to add transitions upon creation of the rotator you can pass them in here. Your transitions obj should look like the code below. Learn how to create your own transition on the transitions page.

var transitions_obj = {
	explode: function(from, to, config) {
		from.blowUp(config.transitionDuration);
		to.fadeIn(config.transitionDuration);
	},
	// will override current fade
	fade: function(from, to, config) {
		from.fadeOut('superDuperSlow');
		to.fadeIn('fast');
	}
}

// pass in like this
jQuery(function($) {
	window.rotator = $('#rotator').rotator({ transitions: transitions_obj });
});

config.interval

Param
inverval Int (in milliseconds)
Default Value
7000

The number of milliseconds between changing slides. 7000 == 7 seconds.

config.slideClass

Param
slideClass String
Default Value
'.slide'

The class used on each slide. This should not be an #id. Be sure to include the preceding dot (.)

config.slideNumClass

Param
slideNumClass String
Default Value
'.slide-#'

The class added to each slide. The class is to tell what number the slide is. Use of # in the class name will be replaced with the slide number.

config.slideIdAttr

Param
slideIdAttr String
Default Value
'slide_id'

This attribute will be added to each slide to help determine the correct slide number. You shouldn't need to change this unless you're strict on your HTML standards.

config.slideNameAttr

Param
slideNameAttr String
Default Value
'slide_name'

This attribute is available for people who want to give a slide a unique name. This name will show up in the data object. It is useful to set this so you can add click tracking with a unique name for the slide.

config.width

Param
width String
Default Value
980

This informs the rotator of it's width so it does not need to check using jQuery or other methods. In some cases (with certain transitions) this is an important setting.

config.height

Param
height String
Default Value
360

This informs the rotator of it's height so it does not need to check using jQuery or other methods. In some cases (with certain transitions) this is an important setting.

config.nav

Param
nav Object
Default Value
{ prev: true, next: true, start: false, stop: false, numbers: true, icons: false, position: 'after' }

This is where you will set most your settings for your nav. There are config options inside this config option so be careful. Below is a short summary of acceptable values for each item. For a full demontstration on how to generate a nav, see the navigation section.

config.nav = {
	prev: bool, // default: true
	next: bool, // default: true
	start: bool, // default: false
	stop: bool, // default: false
	numbers: bool, // default: true
	icons: bool, // default: false
	position: [before|inside|after] // default: 'after'
}

config.currentNavClass

Param
currentNavClass String
Default Value
'.current'

The class used for the current step we are on in the nav. For example, when we switch to slide #3, we will add this class to the step #3 nav item. Cannot be an #id. Be sure to include the preceding dot (.)

config.stopOnClick

Param
stopOnClick Bool
Default Value
true

Do you want to stop auto-rotation once someone clicks on a nav link?

config.loadingClassName

Param
loadingClassName String
Default Value
'loading'

We start the rotator off with a loading class so you can add a loading image for users to see before we show the first slide. We remove this class when the first slide loads. Cannot be an #id. Be sure to leave out the preceding dot (.) on this one.

config.autostart

Param
autostart Bool
Default Value
true

Whether or not to start auto-rotating when the rotator is initially loaded.

config.quickLoad

Param
quickLoad Bool
Default Value
false

If quickLoad is enabled, the rotator will run the start process instantly instead of waiting for slides or window to load.

config.zIndex

Param
zIndex Int
Default Value
10

The CSS z-index number to start the slides off at. This will automatically increase by 2 when transitioning slides. This way you can +/- 1 during transitioning for greater control over your effect.

config.ieFadeFix

Param
ieFadeFix Bool
Default Value
true

Includes a bug fix for IE where pur blacks in the made are shown invisible.

config.events

Param
events Object
Default Value
{ onLoad: function (data) { }, onFirstStart: function(data) { }, onStart: function (data) { }, onStop: function (data) { }, onChange: function (data) { }, onClick: function (data) { }, onNavClick: function (data) { } }

An object of event callbacks that are available to you. By default, the events do nothing even though they are called. You can learn more about adding events on the events page. Here is a list of available events:

config.events = {
	onLoad: function (data) { },
	onFirstStart: function (data) { },
	onStart: function (data) { },
	onStop: function (data) { },
	onChange: function (data) { },
	onClick: function (data) { },
	onNavClick: function (data) { }
}

Retrieving Config Options

If you are going to custom build something like a gallery, you may need to access the config options in your Events, Transitions, etc. To allow you access to the config object, we have added a reference to it at base.config. Please be aware anything you change in here will change globally on this specific instance of the rotator. If you go and change the config.slideIdAttr without realizing it, your rotator may break.

Transitions

Find out the different transitions available to you and how to create your own.

Useful for: Modifying Behaviour, Customizing Transitions, Controlling Slides

Included Transitions

We have included a few common transitions so you don't have to worry about making them on your own. Here is what's already provided for you:

Building Your Own Transitions

Adding your own transition is easy to do once you know the basics. Read on below to start building your own transitions.

Anatomy Of A Transition Function

Here is a sample of what the fade function would look like:

base.transitions.fade = function (from, to, config) {
	from.fadeOut(config.transitionDuration);
	to.fadeIn(config.transitionDuration);
}
Param
from Object (jQuery)
Param
to Object (jQuery)
Param
config Object

In every transition function you have three parameters: from, to, and config. The first two are the jQuery objects of the slides we are transitioning to and from. The config object holds all the configuration options attached to the rotator. With the combination of the two jQuery objects and the config object, you should be able to completely control any effect you want to make between slides.

Adding A Transition To Your Rotator

Ok, so now you know how to make a transition function, here is how you add it to your rotator.

// adding it on creation of rotator
var transitions_obj = {
	explode: function(from, to, config) {
		from.blowUp(config.transitionDuration);
		to.fadeIn(config.transitionDuration);
	},
	// will override current fade
	fade: function(from, to, config) {
		from.fadeOut('superDuperSlow');
		to.fadeIn('fast');
	}
}

// pass in like this
jQuery(function($) {
	window.rotator = $('#rotator').rotator({ transitions: transitions_obj });
});

// adding it after creation
rotator.transitions.zoom = function(from, to, config) {
	from.animate({ width: '200%', height: '200%' });
	to.css({ width: '50%', height: '50%' }).animate({ width: '100%', height: '100%' });
}

Additional Slide Information

Included with the from and to objects is some additional data. Here is what's available to you.

Usage: Each of these values are available in the from and to objects. You can access them by using from.param such as from.id will return the slide id of the from slide. Similarly, to.id will return the slide id of the to slide.

id

Param
id Int

This is the id — a.k.a. slide number — of the slide.

name

Param
name String

This is the unique name of the slide. The unique name is pulled from the attribute you set in config.slideNameAttr.

Events

This will show you the events currently available and how you can act on them.

Useful for: Click Tracking, Engagement Tracking, Manipulating Default Behavior

Available Events

We've included some basic events that most users would need access to. If you feel you need more, go into the core and feel free to add some of your own triggers.

onLoad(data)

Param
data Object

Runs when the rotator first fades in on the page.

onFirstStart(data)

Param
data Object

Runs when the rotator starts auto-rotation for the first time only.

onStart(data)

Param
data Object

Runs when the rotator starts auto-rotation. Will run on every start of the auto-rotation, not just the first start.

onStop(data)

Param
data Object

Runs when the rotator stops the auto-rotation. Will run on every stop of the auto-rotation, not just the first stop.

onChange(data)

Param
data Object

Runs on the change of every slide.

onClick(data)

Param
data Object

Runs when any <a> is clicked inside of a slide. In addition to normal data passed into this function, you get event data as well. You can access it via data.event.

onNavClick(data)

Param
data Object

Runs when any <a> is clicked inside of the rotator nav. In addition to normal data passed into this function, you get event data as well. You can access it via data.event. You will also get navClicked which is information about the slide the nav is navigating to. Here is the form of navClicked:

data.navClicked = {
	id: int, // slide id
	name: string, // unique slide name
	obj: jQuery obj // slide jQuery object
}

Getting Data

Here is how you get and interact with the data object.

disecting data

data Object

You need to understand what information is in data to make good use of it. Here is what event information we give you with data.

var data = {

	// rotator object
	rotator: base,

	// slides information
	slides: {
	  
		// current slide info
		current: {
			// slide num
			id: int,
			// slide name (if available)
			name: string,
			// slide jQuery obj
			obj: jQuery obj
		},
    
		// next slide info
		next: {
			id: int,
			name: string,
			obj: jQuery obj
		},

		// previous slide info
		prev: {
			id: int,
			name: string,
			obj: jQuery obj
		},

		// total slides
		total: int

	}

}

base.getEventData()

Returns
data Object

This will return the same data object as described above. You may use this function at any time.

base.isRunning()

Returns
bool Bool

Find out if the rotator is currently auto-rotating or not. You may use this function at any time.

base.runEvent(name, data)

Param
name String
Param
data Object optional
Returns
base Object (Rotator)

This function is available to you in case you want to run an event at any specific time. You can add more events to the config upon generating of your rotator.

The second parameter allows you to pass in additional data if you want to extend the original data informaton.

base.current()

Returns
slide_id Int

This function will return the slide_id of the current slide we are viewing.

Adding Your Own Events

Learn how to add your own events to the rotator, which you can later call when you'd like.

Creating An Event Callback

You can either override one of the events we currently call, or add your own custom event. Either way, you will create a new event and pass it in upon rotator creation, like so:

var myEvents = {
	// override a predefined event
	onLoad: function (data) {
		console.log('Rotator has loaded successfully');
	},

	// create your own event
	onRightClick: function (data) {
		alert('I\'m sorry, none of that here.');
	}
};

// adding the events on rotator creation
jQuery(function($) {
	window.rotator = $('#rotator').rotator({ events: myEvents });

	// we need to add the right click caller
	rotator.element.click(function(e) {
		if (e.which == 3) {
			rotator.runEvent('onRightClick');
		}
	});

});

Note: Calling an event that doesn't exist will simply not run that event.

Support

eh. not so much.

Sorry

Unfortunately, we do not offer any support at the moment. Rotator.js is made for ease of customization for your smarter-than-average jQuery developer.

License

What you can and can't do with this script

Released under MIT License

We have released our project under the MIT License which is stated as:

Copyright © 2010-2012 by cmfolio & agroism

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.