Learn what Rotator.js is all about and how you can use it.
Rotator.js will take a set of elements on a page and add rotation — or transitions — between them.
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.
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 */ });
});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:
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.
Let's show you how to take full advantage of Rotator.js by setting the various config options available to you.
First, lets show you how to pass in a config object. Then we'll show you what's available.
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);
});Here are all of the config options available to you upon generation of your rotator.
The number of the slide to show first. In case you want to start at slide #3 and go from there.
Whether or not to start on a random slide.
Note: This option will override config.first.
If you chose to show slides in random order, this will reorder the slide nodes in the DOM so they match the shuffled order.
Choose which transition to use between slides. You can add your own transition if you'd like.
The duration of the transition in milliseconds. 1000 == 1 second.
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 });
});The number of milliseconds between changing slides. 7000 == 7 seconds.
The class used on each slide. This should not be an #id. Be sure to include the preceding dot (.)
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.
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.
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.
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.
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.
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'
}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 (.)
Do you want to stop auto-rotation once someone clicks on a nav link?
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.
Whether or not to start auto-rotating when the rotator is initially loaded.
If quickLoad is enabled, the rotator will run the start process instantly instead of waiting for slides or window to load.
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.
Includes a bug fix for IE where pur blacks in the made are shown invisible.
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) { }
}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.
Find out the different transitions available to you and how to create your own.
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:
Adding your own transition is easy to do once you know the basics. Read on below to start building your own transitions.
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);
}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.
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%' });
}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.
This is the id — a.k.a. slide number — of the slide.
This is the unique name of the slide. The unique name is pulled from the attribute you set in config.slideNameAttr.
This will show you the events currently available and how you can act on them.
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.
Runs when the rotator first fades in on the page.
Runs when the rotator starts auto-rotation for the first time only.
Runs when the rotator starts auto-rotation. Will run on every start of the auto-rotation, not just the first start.
Runs when the rotator stops the auto-rotation. Will run on every stop of the auto-rotation, not just the first stop.
Runs on the change of every slide.
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.
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
}Here is how you get and interact with the 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
}
}This will return the same data object as described above. You may use this function at any time.
Find out if the rotator is currently auto-rotating or not. You may use this function at any time.
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.
This function will return the slide_id of the current slide we are viewing.
Learn how to add your own events to the rotator, which you can later call when you'd like.
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.
eh. not so much.
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.
What you can and can't do with this script
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.