New jQuery Content Rotator Plugin
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.
View it on GitHub
jQuery-Content-Rotator 1 0 0 A configurable rotator plugin for jQuery — Read More Latest commit to master on 13/5/2013
Public Methods
MethodDescription
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)
PropertyDescription
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!