About jQuery SlideShow
jQuery Slideshow
The last slideshow you'll ever need.
View the demos, they're radical.
This documentation is released under the Creative Commons - Attribution-NonCommercial-ShareAlike license.
Cheat Sheet
HTML
<!-- styling the height and width is important for some transitions -->
<div id="slideshow" style="width: 400px; height: 200px">
<img src="../img/one.jpg"> <!-- can use any element you want, not just images -->
<img src="../img/two.jpg">
<img src="../img/three.jpg">
<img src="../img/four.jpg">
<img src="../img/five.jpg">
</div>
CSS
Generally you want your slides to be 100% width and height of the slideshow, but you can do whatever you want.
JavaScript
var $el = $('#slideshow');
$el.slideshow({
duration: 400,
delay: 3000,
selector: '> img',
transition: 'push(up)',
autoPlay: true,
show: function (params){
var nextIndex = params.next.index;
if (nextIndex > 2) {
// do something awesome when the slide is after the third slide.
}
},
complete: function (params){
// do something awesome when a transition finishes
}
});
// get the slideshow object if you want it
var slideshow = $el.data('slideshow');
// show the third slide
$el.slideshow( 'show', 2 ); // Element API
slideshow.show(2); // object API
// show the next slide
slideshow.show('next');
// pause and play
slideshow.stop();
slideshow.play();
Custom transitions
You can create your own transitions :D
jQuery.rf.slideshow.defineTransition('slide', function (params, dir, ease){
var animation = {},
prop = (dir == 'left' || dir == 'right') ? 'left' : 'top';
animation[prop] = (dir == 'left' || dir == 'up') ? '-100%' : '100%';
params.previous.animate(animation, params.duration, ease);
});
The name of a transition works like a function, but it's just a string. You can allow for any number of arguments when creating a transition.
For instance, with the slide example, the acceptable transition options could be:
'slide(left)'
'slide(right)'
'slide(up)'
'slide(down)'
'slide(left, linear)'
'slide(left, bounce)'
// in other words
'slide([direction], [easing])'
jQuery.rf.slideshow
jQuery.fn method: slideshow
jQuery UI constructor/element bridge that creates a new slideshow instance on the set of matched elements and stores it on the slideshow
key of the element' data. All instance methods and properties are available through the jQuery wrapper API from the jQuery widget factory bridge.
Signatures
.slideshow(options)
.slideshow(method, [methodArg [, methodArgN]])
.slideshow(property [, value])
Arguments
options
(object) - Key value pairs of options, see jQuery.rf.slideshow for more information.
method
(string) - The method name as a string to call on the slideshow instancemethodArg
(mixed) - The argument(s) to send to the method
property
(string) - The property name to get or set from the slideshow instance (will get ifvalue
parameter is omitted)value
(mixed) - The value to set the property to on the slideshow instance
Returns
Object - A jQuery object
Examples
var el = $('#slideshowElement')
// create an instance of slideshow with a few options
el.slideshow({
selector: 'img',
delay: 5000,
duration: 500,
transition: 'fadeThroughBackground'
});
// call a method through the jQuery UI bridge API
el.slideshow('show', 2); // shows the third slide
// get the instance out of the elements data
var slideshow = el.data('slideshow');
// call methods directly on the instance
slideshow.show(2);
slideshow constructor: jQuery.rf.slideshow
The slideshow constructor function created by jQuery UI widget factory.
Signature
new jQuery.rf.slideshow(options, node)
Arguments
options
(object) - An object map of key value pairstransition
(string, default'fade'
) - The default transition to use. Slideshow ships with: push, slide, blind, fade, crossFade, fadeThroughBackground, and none. Read more about transitionsselector
(css selector string, default'> *'
) - A CSS selector that defines which children elements are the slides. The default selects immediate children.initialIndex
(number, default0
) - Which slide to show upon on initialization by index.autoPlay
(boolean, defaultfalse
) - Automatically cycles the slideshow without having to call theplay
method.delay
(number, default:3000
) - The time in milliseconds a slide is displayed.duration
(number, default:400
) - The time in milliseconds a transition animates.resetTimerOnShow
(boolean, default:true
) - If true, whenshow
is called while the slideshow is playing, the delay timer is reset. If false, callingshow
does not interrupt the timer and you will get two transitions (or more) for one delay cycle.autoStyle
(boolean, default:true
) - Automatically sets the style properties on your elements that most transitions need:{ left: 0, top: 0, position: 'absolute' }
for slides and positionrelative
for the parent element if position is static.
node
(element) - A DOM element (not a jQuery wrapped collection)
Returns
Object A slideshow instance object.
Examples
// generally, jQuery widgets don't do it like this :P
var slideshow = new jQuery.rf.slideshow({
transition: 'push(left, swing)',
selector: '.slide'
}, $('#slideshow)[0]);
// if you want an object to work with this is more jQuery-esque...
var slideshow = $('#slideshow').slideshow({
transition: 'push(left, swing)',
selector: '.slide'
}).data('slideshow');
slideshow function: defineTransition
Defines a slideshow transition, the muscle behind slideshow. I encourage you to read the source where the out-of-the-box transitions are defined. Mastering this function will allow you to flippin' sweet slideshows.
Signature
jQuery.rf.slideshow.defineTransition( name, transition )
Arguments
name
(string) - The name of the transition.transition
(function) - The function called when the slideshow uses the transition.Signature
function ( params [, argN] )
Arguments
params
(object) - Information about the transition and slideshow instance:previous
($element) - The previous slide, already wrapped with jQuery.next
($element) - The next slide, already wrapped with jQuery.duration
(number) - The duration of the transition.instance
(object) - The slideshow instance, for convenience.
argN
(mixed) - Transition names are actually quasi-functions that take parameters that get passed through as arguments to the transition function. See examples for details.
Returns
undefined
Examples
// fade is about simplest transition
jQuery.rf.slideshow.defineTransition('fade', function( params ){
// the previous slide is on top with z-index 1, and the next slide has z-index 0
// ... so we can simply fade the previous slide out and use the params.duration
params.previous.fadeOut( params.duration );
});
// The slide transition is a bit more complex
jQuery.rf.slideshow.defineTransition('slide', function ( params, direction, fade, ease ){
// You can pass arguments to a transition (so cool)
// direction, fade, and ease all come from the transition option the user defines
var animation = {}, // animation options to build up
// figure out which property to animate based on the direction
prop = ( direction === 'left' || direction === 'right' ) ? 'left' : 'top';
// set the animation property and value
animation[prop] = ( direction === 'left' || direction === 'up' ) ? '-100%' : '100%';
// check the fade argument and add opacity to the animation
if (fade) animation.opacity = 0;
// perform the animation and slide the previous element out
params.previous.animate( animation, params.duration, ease );
});
// and the usage:
$('#el').slideshow({
transition: 'slide(left, true, linear)' // here's where the arguments come from
});
Notes
As you can see from the examples, transition strings get parsed like functions and pass the values into the transition. The values true, false, null, undefined and '' values will be converted to their primitive types.
slideshow method: show
Transitions from the current slide to another.
Signature
slideshow.show( what, options )
$element.slideshow( 'show', what, options )
Arguments
what
(mixed) - Accepts the strings'next'
and'previous'
or the index of the slide you want to show, ie:2
options
(object) - Can override the instance optionsduration
andtransition
for just this transition.
Returns
Object Returns the slideshow object or the jQuery collection.
Examples
var $element = $('#slideshow').slideshow(); // create slideshow, store element
var slideshow = $element.data('slideshow'); // get slideshow instance
// show 3rd slide
$element.slideshow( 'show', 2 ); // $element API
slideshow.show( 2 ); // object API
// show next slide
$element.slideshow( 'show', 'next' ); // $element API
slideshow.show( 'next' ); // object API
// show previous slide with options
$element.slideshow( 'show', 'next', {
transition: 'push(right)',
duration: 1000
}); // $element API
slideshow.show( 'next', {
transition: 'push(right)',
duration: 1000
}); // object API
slideshow method: play
Transitions slides on an interval defined in options.delay
.
Signature
slideshow.play()
$element.slideshow( 'play' )
Returns
Object Returns the slideshow object or the jQuery collection.
Examples
var $element = $('#slideshow').slideshow(); // create slideshow, store element
var slideshow = $element.data('slideshow'); // get slideshow instance
$element.slideshow( 'play' ); // $element API
slideshow.play(); // object API
slideshow method: stop
Stops the slideshow when cycling.
Signature
slideshow.stop()
$element.slideshow( 'stop' )
Returns
Object Returns the slideshow object or the jQuery collection.
Examples
var $element = $('#slideshow').slideshow(); // create slideshow, store element
var slideshow = $element.data('slideshow'); // get slideshow instance
$element.slideshow( 'stop' ); // $element API
slideshow.stop(); // object API
slideshow property: element
$element - The jQuery wrapped slideshow element
slideshow.element
$element.slideshow( 'element' )
slideshow property: slides
Array - The jQuery wrapped slide elements.
slideshow.slides
$element.slideshow( 'slides' )
slideshow property: current
Number - The index of the current slide.
slideshow.current
$element.slideshow( 'current' )
slideshow property: playing
Boolean - True if playing.
slideshow.playing
$element.slideshow( 'playing' )
slideshow property: transitioning
Boolean - True if in the middle of a transition.
slideshow.transitioning
$element.slideshow( 'transitioning' )
slideshow event: show
Fires when the slideshow starts a transition.
Signature
function( event, eventData )
Arguments
event
(null) - I'm honestly not sure why this exists for widget custom events :\eventData
(object) - Data about the eventnext
(object) - Information about the next element.element
($element) - The next element, wrapped by jQuery.index
(number) - The index of the next slide.
previous
(object) - Information about the previous element.element
($element) - The previous element, wrapped by jQuery.index
(number) - The index of the previous slide.
instance
(object) - The slideshow instance.
Examples
// element API, can pass in as an option
var $el = $('#slideshow').slideshow({
show: function ( event, eventData ){
// do something with eventData
if (event)
}
});
// or can add it later
var slideshow = $el.data('slideshow'); // get the instance
slideshow.bind('slideshowshow', function(){
// do something
});
slideshow event: complete
Fires when a slideshow transition ends.
Signature
function( event, eventData )
Arguments
event
(null) - I'm honestly not sure why this exists for widget custom events :\eventData
(object) - Data about the eventnext
(object) - Information about the next element.element
($element) - The next element, wrapped by jQuery.index
(number) - The index of the next slide.
previous
(object) - Information about the previous element.element
($element) - The previous element, wrapped by jQuery.index
(number) - The index of the previous slide.
instance
(object) - The slideshow instance.
Examples
// element API, can pass in as an option
var $el = $('#slideshow').slideshow({
complete: function ( event, eventData ){
// do something with eventData
if (event)
}
});
// or can add it later
var slideshow = $el.data('slideshow'); // get the instance
slideshow.bind('slideshowcomplete', function(){
// do something
});
slideshow css: next
During a transition, the next element gets the CSS class .slideshow-next
.
slideshow css: previous
During a transition, the previous element gets the CSS class .slideshow-previous
.
slideshow css: current
The current slide gets the css class .slideshow-current
.
slideshow css: transitioning
During a transition, the slideshow element gets the css class .slideshow-transitioning
.