New jQuery Content Rotator Plugin
This is an official release of a jQuery plugin I wrote some time ago and have been using and updating a lot lately. I’ve decided to release it here, and on jQuery, because I’ve finally got all of the bugs out and it has enough options and methods to work for any job. As devlopers we get a lot of requests for some image slideshow or content slideshow at the top of the homepage or some subsequent page. I’ve browsed jQuery’s image rotator options a dozen times and had a really hard time finding something that just worked. Lots of authors out there are creating plugins that are styled one way by default, come with too many requirements for the layout, or that just break; and so I’m throwing my hat into the ring. This plugin creates an image (or content) slideshow based on any nested element.
So you can create a slideshow from a nested list (like many others will do) or you can nest divs and target the top containing div. You could nest spans if you’d like (don’t know why) but any DOM element will work. You can make it auto rotate, loop infinitely, set the delay, set the transition speed and control the movement with external controls via it’s public methods. I know that if you need some content on the stage to scroll for any reason, in any direction, and need any control over it that this is the plugin that works and will do it.
Below is the documentation for the plugin. Included in the zip is a demo page, a slightly styled demo with most of the options set, the documentation again, and jQuery 1.4.2 as well as an uncompressed and compressed version of the plugin. The uncompressed version is documented as well.
Download the plugin!
Public Methods
| Method |
Description |
| rotator |
Creates a new instance of the rotator plugin |
| goNext |
Sends the rotator to the next child index |
| goToIndex |
Sends the rotator to the user defined index in the parameter |
| onError |
Dispatches an error object relaying the target failure and error message |
| pause |
Pauses the rotator. |
| start |
Starts the rotator. |
Public Properties (options)
| Property |
Description |
| arrows |
The class of the left and right arrow controls with unique number 0 indexed |
| tranSpeed |
The time a transition should last in milliseconds |
| delay |
The time a child should display before the transition in milliseconds |
| auto |
Sets auto scrolling through rotator. true starts animation automatically. false disables auto rotating |
| loop |
Infinite scroll on or off, default true infinitely loops |
| backwards |
sets the rotator to run backwards. Loop must be set to true to run backwards |
| onChange |
onChange event fires when the transition animation begins |
| endChange |
endChange event fires when the transition animation ends |
| Method Detail |
rotator
Description: Creates a new instance of the rotator plugin
$(“.slider”).rotator(); |
goNext
Description: Sends the rotator to the next child index
$(“.slider”).data(‘rotator’).goNext();
goNext also accepts a parameter of 1 or -1. This will cause the rotator to either rotate backwards to the previous child or continue forwards. |
goToIndex
Description: Sends the rotator to the next child index
$(“.slider”).data(‘rotator’).goToIndex(2);
The rotator will animate to the child specified. If the child is out of range an error is thrown and the rotator will continue on like normal. |
onError
Description: Dispatches an error object relaying the target failure and error message
$(“.slider”).data(‘rotator’).onError = function(e){alert(“error in “+e.target)}
The error object contains two properties; target and error. The target is where the rotator failed. For example, it may be in the initializing
where too few children are present in the slider ( the target would be init) or when goToIndex is called with an index out of range (target is goToIndex).
The error is a descriptive error message of the failure. |
pause
Description: Pauses the rotator
$(“.slider”).data(‘rotator’).pause();
Clears the interval at which the slider is rotating if auto is true (default). |
start
Description: Starts the rotator
$(“.slider”).data(‘rotator’).start();
Starts the rotator rotating regardless of auto. Can be used to restart a paused rotator
or start a rotator whose auto property is set to false. This will set auto to true and the
rotator will continue rotating until paused again. |
| Property Detail |
arrows
Description: The class of the left and right arrow controls with unique number 0 indexed
$(“.slider”).rotator({arrows:{left:”.leftArrow”,right:”.rightArrow”}});
arrows is an object containing class identifiers for the left and right arrow DOM objects.
Default: {left:”.leftArrow”+i,right:”.rightArrow”+i}
Where i is the 0 based increment of the number of sliders on the page. |
tranSpeed
Description: The time a transition should last in milliseconds
$(“.slider”).rotator({tranSpeed:400});
Default: 800 |
delay
Description: The time a child should display before the transition in milliseconds
$(“.slider”).rotator({delay:10000});
Default: 4000 |
auto
Description: Sets auto scrolling through rotator. true starts animation automatically. false disables auto rotating
$(“.slider”).rotator({auto:false});
Default: true |
loop
Description: Infinite scroll on or off, default true infinitely loops
$(“.slider”).rotator({loop:false});
If set to false the slider will scroll back to the 0 index when it has reached the last child
Default: true |
backwards
Description: Sets the rotator to run backwards. Loop must be set to true to run backwards
$(“.slider”).rotator({backwards:false});
The rotator will rotate from left to right instead of right to left by default
Default: false |
onChange
Description: onChange event fires when the transition animation begins
$(“.slider”).rotator({onChange:function(i){alert(‘next’)}});
When the onChange event is fired a parameter is passed containing the new index of the rotator
Default: function(){} |
endChange
Description: endChange event fires when the transition animation ends
$(“.slider”).rotator({endChange:function(i){alert(‘next’)}});
When the endChange event is fired a parameter is passed containing the new index of the rotator
Default: function(){} |
Download the plugin!
28 Comments
Is there a way to modify this so that I can use a different image for each of the dots for numbering?
Instead of having the dots as a way of numbering at the top, I want to have 3 large buttons on the bottom as navigation. but I need “dot” or button, to be a different background image in each of the 3. is there a way to modify the javascript so that each of the li’s it creates, are named with different classes? li class=1, li class=2, li class=3?
does that make sense?
There isn’t anything built into it to give each dot a unique class. However, the dots do get a wrapper class, slider-numbers, and each instance gets a unique class slider-numbersN where N is the index of the instance. You could, after initiating the plugin, use jQuery to give each li a class.
$(“.slider-numbers li”).each(function($){
$(this).addClass(“number-”+i);
});
Then each list element will have the class number-0, number-1, number-2 and so on. I hope that helps.
An example of this script in action would be nice to see!!!
There are several in the download in demo.html. I may put one up in the next few days though.
Is there a way to implement an onmouseover event that would keep the rotator from changing only while hovering?
Great plugin by the way!!
Hmmm, there isn’t one built into it, nor a way to do it at this point. However, it would be easy to implement as either an option or method. I’ll put that in the next update for sure and email you. Thank you!
Where’s an example of this plugin?
My homepage, recently updated, is using this plugin. Additionally, examples of the plugin can be seen in the demo folder packaged with the download for this plugin.
Great Plugin, one question: how to deactivate the fading? it always stops between every element, also if i have delay 0. ?? thanks
There is not any fading applied to the elements in the rotator by my plugin so I am a little confused by what you mean on the fading. Also, it is not meant to continuously scroll with a delay of 0. That is a great idea but it would probably cause the plugin the go nuts right now! I probably should have implemented a minimum check on the delay. If you are looking for something to continuously scroll your content then unfortunately this is not the plugin for you.
Is there a way to make this scroll vertically?
There isn’t. It’s definitely something I thought of though. I’ve been a bit behind lately but I’m planning on adding some features to this. I’ll put that in the next version and email you. If you get to it first I’d be more than happy to integrate it; with due credit of course. Thank you!
One more thing, I have an example where the thumbnail link icons need to be graphically unique. In your styled example I noticed that it only styles the links as the same with the active state being the only different one.
Any advice on making each link and active state unique? Is there somewhere in the Javascript where I can assign a unique class, iterate that and then append to the link element?
Thanks
Hey Eugene,
Thanks again for the feedback. Andrew asked the same type of question. His is the first comment. Check out my answer there. You can loop over each “thumbnail” to give it a unique class and then style each thumbnail accordingly in the css.
Thanks for your rapid response.
Unfortunately that solution did not work however here’s something I cooked up that did:
$(document).ready(function() {
$(“.slider-numbers-0 li a”).each(function(i) {
$(this).addClass(“item”+(i+1));
});
});
Well… when i change height and width of the slider-divs, the whole rotator goes crazy (skips tons of pictures)… what am i doing wrong?
I’d need to see your markup. But in general, I can say make sure any div you want to show per slide is set to the width and height of the viewable area and that it is floated left. The container for the slider should also have it’s height set to the same as the viewable height but the plugin will set the width. If those few things are not done then the rotator may not work as expected. If you can provide a link to the problem I will take a look at it.
Mneil , i am working on a Commmecial website template, i am using you jquery query plugin , can i use the images too ?
I guess I didn’t mention that anywhere in the documentation; but thank you for asking. Unfortunately you cannot use these images in your site as they are licensed to the owners of the documentation and my previous employers. I’ve been working on an update and will probably swap these out for some stock photos. Sorry.
Excellent plugin, thanks! I need to add a pause button. Any advice on how I might be able to do that?
There wasn’t a way. But I’d been asked that before so I went ahead and added pause and start methods so you can do that. I added it to the documentation and in the demo.html. Redownload the plugin. Thanks!
Wow, thanks a million! That works like a champ. That will certainly prove useful to everyone using this plugin. I really appreciate how responsive you are to this comment thread. Please keep up the great work!
FYI, I made a minor tweak to your code that you might be interested in. Rather than having two separate buttons for pause/start, I wanted one that toggles back and forth on click. This is what I’m using:
$(“.pausebutton”).toggle(
function() {
$(“.slider-5″).data(‘rotator’).pause();
$(“.pausebutton”).css({ “background-image” : “url(images/btn_play.png)” });
},
function() {
$(“.slider-5″).data(‘rotator’).start();
$(“.pausebutton”).css({ “background-image” : “url(images/btn_pause.png)” });
}
);
There is probably a cleaner way to do it, but this seems to work just fine.
Thanks again!
hi this is just what i wanted, will combine with flash with mouseovers controling this using gotoIndex() but too would like to call back to flash to tell him which image is just on and what to do but …
when is use the onChange or onChangeEnd like this
$(‘.slider2′).rotator({onChangeEnd:function(i){ $(“#infodiv”).html(‘next is ‘+i); }});
the gallery stops running smoothly in order 1 > 2 > 3 > 4 > 5 > 1 … etc and starts not scrolling to the next pic, but scrolls some next pic in order looking random to me (scrolls quickly over images about 4-5 images while displays the one normally /looks like its launching gotoIndex(i) in some weird way / )
am I doing something wrong ?
I have seen the rotator jump indices before but it’s usually because of a conflict with something else. What you are doing looks fine. Can you package up an example that works incorrectly and send it to me? I will take a look at it and see if I can’t find the problem from there. Otherwise, this is a pretty tough thing for me to fix; it could be a hundred things. Please point me to an example of your problem. Thanks.
sorry I was a complete dumbhead
I just blindly copied it from your examples and pasted as a NEW line to the script instead of adding the onChange to the rest just two lines above so there were actually initialized two rotators on the same div … well everything looks bad until you find out its your own small mistake maybe this may be fixed in some next version to check whether there already is a rotator active and add the option
anyway thanks for a great script and prompt responses from you this script is going to rock FTW
When I use 1-10 images it works fine. When I use 40-50 images the rotater script goes crazy and fast forwards through everything. Has anyone else had this issue? Any resolution?
I haven’t tested it with that many images but I don’t see why it wouldn’t continue to work as normal. Are there any other scripts on the site, have you isolated the plugin to test it and make sure that nothing else is interfering with it? And, if you have, are any errors showing up in the console?