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

 

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!

Posted in JavaScript
+ anonymous users