Really Simple Slideshow Logo

Really Simple™ Slideshow

Really Simple Slideshow is a jQuery plugin for creating image slideshows. Images are loaded dynamically as each one is required, allowing for larger slideshows without having to pre-load lots of images.

A Really Simple Demo

The slideshow above uses default settings, and is initialised with one line of code, shown here attached to the jQuery document ready event:

$(document).ready(function () {
	$('#slideshow-div').rsfSlideshow();
});

By default, the slideshow looks for slide data within the markup. Here's how the HTML looks:

<div id="slideshow-div" class="rs-slideshow">
	
	<!-- 
	Set up an initial slide -- this provides an image for users without JavaScript 
	-->
	<div class="slide-container">
		<img src="demo/images/morzine-2011-c.png" 
			alt="The first image in a slideshow demo." title="This is the first slide" />
	</div>
	
	<!-- 
	This list contains data about each slide. 
	So that the slide images aren't loaded with the page, we use <a> tags. 
	With some extra CSS rules, this allows for users without JavaScript to 
	access the images by clicking the links. 
	-->
	<ol class="slides">
		<li>
			<a href="demo/images/morzine-2011-c.png">morzine-2011-c.png</a>
		</li>
		<li>
			<a href="demo/images/morzine-2011-a.png">morzine-2011-a</a>
		</li>
		<li>
			<a href="demo/images/morzine-2011-b.png">morzine-2011-a</a>
		</li>
	</ol>
	
</div>

And the CSS:

.rs-slideshow {
	border: 12px solid #444;
	height: 240px;
	margin: 24px auto;
	overflow: hidden;
	position: relative;
	width: 620px;
}

.rs-slideshow .slide-container {
	background-color: #444;
	height: 100%;
	left: 0;
	overflow: hidden;
	position: absolute;
	top: 0;
	width: 100%;
}

.rs-slideshow .slide-container img {
	position: absolute;
}

/*	Hide the slide data container	*/
.rs-slideshow .slides {
	display: none;
}

Note: The demos on this page use the CSS3 border-radius property. In order to keep the demo code on this page simple and easy to read, these CSS rules aren't shown here. If you download the demo code, you'll find this extra code there.

Captions and Links

Captions can be added and slide images can be made clickable, simply by adding to the HTML. This can also be done programatically—we'll get to that later.

Notice the changes to the HTML:

<div id="slideshow-div">
	
	<!-- 
	Set up an initial slide -- this provides an image for users without JavaScript. 
	Notice that we've also added the caption for the first slide.
	-->
	<div class="slide-container">
		<img src="demo/images/morzine-2011-c.png" 
			alt="The first image in a slideshow demo." 
			title="This is a caption for the first slide" />
		<span class="slide-caption">This is a caption for the first slide</span>
	</div>
	
	<!-- 
	We can add optional captions and links for each slide directly to the markup. 
	(This can also be done programatically, using the API&mdash;see below for details)
	-->
	<ol class="slides">
		<li>
			<a href="demo/images/morzine-2011-c.png" 
				title="This is a caption for the first slide">This is a caption for the first slide</a>
		</li>
		<li>
			<a href="demo/images/morzine-2011-a.png" 
				title="This is a caption for the second slide, and this slide is clickable!" 
				data-link-to="http://reallysimpleworks.com">This is a caption for the second slide</a>
		</li>
		<li>
			<a href="demo/images/morzine-2011-b.png" 
				title="This is the third slide">This is a caption for the third slide</a>
		</li>
	</ol>
	
</div>

Some additional CSS for the caption element:

.slide-container .slide-caption {
	background-color: #000;
	bottom: 0;
	color: #fff;
	display: block;
	left: 0;
	padding: 6px 12px;
	position: absolute;
	text-align: center;
	right: 0;
	filter: alpha(opacity=70);
	-khtml-opacity: 0.7;
	-moz-opacity: 0.7;
	opacity: 0.7;
}

Adding Controls

The slideshow below uses same HTML markup and CSS as the previous examples (with a couple of extra slides), but initiates the slideshow with some additional options to add controls.

Here's how this is done:

$('#slideshow-controls').rsfSlideshow({
	controls: {
		playPause: {auto: true},
		previousSlide: {auto: true},
		nextSlide: {auto: true},
		index: {auto: true}
	}
});

For full details on using the controls options, please see the controls reference section.

Basic Customisation

The slideshow below uses exactly the same HTML markup and CSS as the previous example, but initiates the slideshow with some additional options.

Here's how this is done:

$('#slideshow-div').rsfSlideshow({
	interval: 3,
	transition: 500,
	effect: 'slideLeft'
});

Effect Sequences

In the previous example, the effect property is a string, specifying a single transition effect for our slideshow. We can, however, use an object instead, which allows us to create a sequence of transition effects. The slideshow below demonstrates this.

Here's the code:

$('#slideshow-div').rsfSlideshow({
	interval: 3,
	transition: 500,
	effect: {
		effects: Array('slideUp', 'slideLeft', 'slideRight'),
		iteration: 'backAndForth'
	}
});

Notice that the effect property is now an object with two properties of its own: effects and iteration.

effects is an array of transition effects, and iteration determines the way in which we loop through these effects.

There are three possible values for iteration:

  • 'loop' causes the slideshow to loop through the specified array of effects, starting from the beginning when the last one is reached.
  • 'backAndForth' will move back and forth through the array of specified effects, changing direction at each end.
  • 'random' will randomly select an effect from the specified array on each transition.

See the transition effects reference for more on transition effect settings.

Adding Slides Programatically

So far, we've used markup to pass slide data to the slideshow, but there's another way to do this.

The first image in a slideshow demo. This is a caption for the first slide

The HTML is much neater, as we only need to set up the initial slide for non-JavaScript users:

<div id="slideshow-div">
	
	<!-- 
	Set up an initial slide -- this provides an image for users without JavaScript.
	-->
	<div class="slide-container">
		<img src="demo/images/morzine-2011-c.png" 
			alt="The first image in a slideshow demo." title="This is the first slide" />
		<span class="slide-caption">This is a caption for the first slide</span>
	</div>
	
</div>

We then add slides using JavaScript. Here's how the code looks:

//	Create an array of slide objects
var slides = Array(
	{
		url: 'demo/images/morzine-2011-c.png', 
		caption: 'This is a caption for the first slide'
	},
	{
		url: 'demo/images/morzine-2011-a.png',
		caption: 'This is a caption for the second slide, and this slide is clickable!',
		link_to: 'http://reallysimpleworks.com'
	},
	{
		url: 'demo/images/morzine-2011-b.png',
		caption: 'This is a caption for the third slide'
	}
);

//	Add the slides on initialisation
$('#slideshow-div').rsfSlideshow({slides: slides});

This has exactly the same effect as the very first example above.

If you watch the slideshow above, you'll notice that there are actually five slides. The additional two are added later, using the API. Here's how:

//	Create the new slide objects
var slides = Array(
	{
		url: 'demo/images/lancs-yorks.png', 
		caption: 'This is a caption for the fourth slide'
	},
	{
		url: 'demo/images/cragg-road.png', 
		caption: 'This is a caption for the fifth slide'
	}
);

//	Add the new slides using the API
$('#slideshow-div').rsfSlideshow('addSlides', slides);

This demonstrates adding multiple slides, contained within an array, but you can also pass a single slide object—or even to just an image URL—to the addSlides method.

We can add slides to the end of the slideshow at any time using this method, which allows for the loading and insertion of additional slides at a later time.

Options

Options are set by passing them as an object on initialisation. For example:

$('#slideshow-div').rsfSlideshow({
	interval: 3, 
	transition: 500, 
	slides: slides
});

Methods

API methods can be called on any initialised slideshow as follows:

$('#slideshow-div').rsfSlideshow('methodName', parameters);
  • addSlides

    Add one or more slides to the end of the slideshow. See The Slide Object for more details.

    var slides = Array(
    	{
    		url: 'slide-image-url.png',
    		caption: 'Slide catpion text',		//	(optional)
    		link_to: 'url-to-link-slide-to',	//	(optional)
    		effect: 'slideUp'					//	(optional)
    	},
    	{
    		url: 'another-slide-image-url.png'
    	},
    	...
    )
    $('#slideshow-div').rsfSlideshow('addSlides', slides);
  • removeSlides

    Remove slides from the slideshow.

    Called without any arguments, this method will remove all slides from the current slideshow.

    $('#slideshow-div').rsfSlideshow('removeSlides');

    You can also pass an integer, or an array of integers, to the method in order to remove specific slides at given positions in the slides array:

    //	Remove the slide at key 2 (the third slide) 
    $('#slideshow-div').rsfSlideshow('removeSlides', 2);
    //	Remove the slides at keys 1, 4 and 6 (the 2nd, 5th and 7th slides) 
    $('#slideshow-div').rsfSlideshow('removeSlides', [1,4,6]);

    Note that when slides are removed the slides are repositioned within the array. The following code, for example, will remove two slides from the beginning of the slides array:

    $('#slideshow-div').rsfSlideshow('removeSlides', 0);
    //	The second slide has now become the first, and is removed by the next line
    $('#slideshow-div').rsfSlideshow('removeSlides', 0);

    Slide keys passed within an array, however, will only be removed once. The following code will only remove the first slide:

    $('#slideshow-div').rsfSlideshow('removeSlides', [0,0]);

    It's a good idea to call the stopShow method before removing slides, in order to prevent errors where slide data is not found.

  • getSlideData

    Returns a slide object or the entire array of slide objects

    //	Return the entire slides array
    $('#slideshow-div').rsfSlideshow('getSlideData');
    //	Return the slide object for the third slide
    $('#slideshow-div').rsfSlideshow('getSlideData', 2);
  • startShow

    Start the slideshow. By default, the slideshow will start automatically on initialisation—to prevent this behaviour, use the autostart option.

    $('#slideshow-div').rsfSlideshow('startShow');
  • stopShow

    Stop the slideshow.

    $('#slideshow-div').rsfSlideshow('stopShow');
  • toggleShow

    Starts the slideshow if currently stopped, or stops the slideshow if currently running.

    $('#slideshow-div').rsfSlideshow('toggleShow');
  • nextSlide

    Load and transition into the next slide in the slideshow.

    $('#slideshow-div').rsfSlideshow('nextSlide');
  • previousSlide

    Load and transition into the previous slide in the slideshow.

    $('#slideshow-div').rsfSlideshow('previousSlide');
  • goToSlide

    Load and transition into the slide at the provided key in the slides array.

    var slide_key = 3;
    $('#slideshow-div').rsfSlideshow('goToSlide', slide_key);
  • currentSlideKey

    Returns the array key of the current slide.

    $('#slideshow-div').rsfSlideshow('currentSlideKey');
  • totalSlides

    Returns the total number of slides currently in the slides array.

    $('#slideshow-div').rsfSlideshow('totalSlides');
  • isRunning

    Returns true if the slideshow is running, false if not.

    $('#slideshow-div').rsfSlideshow('isRunning');
  • addControl

    Generates a control for the slideshow and adds it to the DOM, according to settings specified as options.

    $('#slideshow-div').rsfSlideshow('addControl', type);

    type must be one of: 'playPause', 'previousSlide', 'nextSlide' or 'index'.

    Note: only use this method if you haven't set controls to auto-generate using options.

  • bindPlayPause

    Binds an element(s) on the page to play/pause functionality for the slideshow.

    Note: when controls are auto-genreated, this is taken care of. Only use this method when you're creating your own controls on the page, and need to bind this functionality to them.

    $('#slideshow-div').rsfSlideshow('bindPlayPause', $playPause);

    $playPause (required) is the play/pause control element to bind the behaviour to, as a jQuery object.

  • bindPrevious

    Binds an element(s) on the page to "previous slide" functionality for the slideshow.

    Note: when controls are auto-genreated, this is taken care of. Only use this method when you're creating your own controls on the page, and need to bind this functionality to them.

    $('#slideshow-div').rsfSlideshow('bindPrevious', $prev, autostop);

    $prev (required) is the "previous slide" control element to bind the behaviour to, as a jQuery object. The autostop parameter is optional, and if true (default) causes the slideshow to pause whenever the control is clicked.

  • bindNext

    Binds an element(s) on the page to "next slide" functionality for the slideshow.

    Note: when controls are auto-genreated, this is taken care of. Only use this method when you're creating your own controls on the page, and need to bind this functionality to them.

    $('#slideshow-div').rsfSlideshow('bindNext', $next, true);

    $next (required) is the "next slide" control element to bind the behaviour to, as a jQuery object. The autostop parameter is optional, and if true (default) causes the slideshow to pause whenever the control is clicked.

  • bindIndex

    Binds an element(s) on the page to "go to slide x" functionality for the slideshow.

    Note: when controls are auto-genreated, this is taken care of. Only use this method when you're creating your own controls on the page, and need to bind this functionality to them.

    $('#slideshow-div').rsfSlideshow('bindIndex', $index, true);

    $index (required) is the set of index control elements to bind the behaviour to, as a jQuery object. The autostop parameter is optional, and if true (default) causes the slideshow to pause whenever the an index control is clicked.

    If the ID of your slideshow element is 'my-slideshow' your "slide x" controls should be marked up as follows:

    <a href="#" class="rs-next" data-control-for="my-slideshow" data-slide-key="0">1</a>
    <a href="#" class="rs-next" data-control-for="my-slideshow" data-slide-key="1">2</a>
    <a href="#" class="rs-next" data-control-for="my-slideshow" data-slide-key="2">3</a>
    ...etc...

    This expected markup can be customised by assigning your own methods within the index: {getEach: function() {...your method here...}} and index: {getSlideKey: function() {...your method here...}} properties in the controls options.

Transition Effects

The effect setting is a string, an array, or an object (see the effect option reference for details). Currently, the valid effect names are as follows:

  • 'fade' — fade from one slide to the next
  • 'slideLeft' — slide the previous slide out and the new slide in, from right to left
  • 'slideRight' — as above, from left to right
  • 'slideUp' — as above, upwards
  • 'slideDown' — as above, downwards
  • 'none' — no effect; slides switch instantly from one to the next

When passing an object as the effect setting, the second parameter, iteration, specifies the way in which the transition effects are selected for use. Here are the available options:

  • 'random' — an effect is randomly selected from the specified array of effect names
  • 'loop' — the specified array of effect names is looped through, starting again at the first once the end of the array is reached
  • 'backAndForth' — the specified array of effect names is iterated through forwards, and when the end is reached, is iterated through backwards, until back at the start of the array, where this process begins again

See this demonstration for a working example of the iteration parameter in use.

The Slide Object

The slide object is used to add a slide to the slideshow. It has one required property, and some optional ones:

var slide = {
	// The image URL (required) 
	url: 'url-of-slide-image.png',	
	// The text for the slide caption (optional) 
	caption: 'Caption text goes here',	
	// The URL to link the image to when clicked (optional)
	link_to: 'url-to-link-to',	
	// A string specifying the effect to use when transitioning to this slide (optional)
	// This overrides the global effect settings for the slideshow
	effect: 'slideLeft'	
};

Slideshow Events

Really Simple™ Slideshow triggers various events, each of which can have handlers bound to them, just like any jQuery event:

$('#my-slideshow').bind('rsStartShow', function() {
	alert('The slideshow has started!');
});

The following slideshow events are currently supported:

  • 'rsStartShow' — triggered whenever the slideshow is started
  • 'rsStopShow' — triggered whenever the slideshow is stopped
  • 'rsPreTransition' — triggered when the slide is requested, but before the slide image has loaded
  • 'rsImageReady' — triggered when the image for the slide has loaded
  • 'rsPostTransition' — triggered when the transition has completed, and the slide is in place
  • 'rsLastSlide' — as 'rsPostTransition' but only triggered on the last slide of the slideshow
  • 'rsFirstSlide' — as 'rsPostTransition' but only triggered on the first slide of the slideshow

Download

Issues

Please report bugs, etc. using GitHub.

Browser Support

We've tested Really Simple™ Slideshow in the latest versions of Chrome, Safari, Opera and Firefox, and IE versions 6–9.

License

Really Simple™ Slideshow is released under the MIT license and is free to use for both commercial and non-commercial projects.

Change Log

Version 1.4.8 — 5 Jul 2011

  • All public methods now return a jQuery collection (unless they return specific data).
  • QUnit test suite updated to include tests for all public methods.

Version 1.4.7 — 30 Jun 2011

  • Improved the handling of the removal of outgoing slide elements.
  • Moved all transition effects into the $.refSlideshow.transitions object, allowing for extension of the slideshow effects.
  • Added an asynchronous method for determining image dimensions, which prevents an occasional race condition in Chrome (previously caused the slideshow not to start in Chrome, in certain situations).
  • Added a CSS rule to fix the broken fade transition effect in IE8.

Version 1.4.6 — 1 Jun 2011

  • Added support for optional image alt and title parameters (requires custom options). [Thanks to Richard Dean for this contribution]

Version 1.4.5 — 27 May 2011

  • Added HTML cpations demo.
  • Accommodated for HTML captions.
  • Changed caption container element from span to div.
  • Removed the broken controlsdemo.html

Version 1.4.4 — 18 May 2011

  • Fixed bug causing fatal "Object doesn't support this..." error in IE 6/7/8.

Version 1.4.3 — 17 May 2011

  • Fixed bug causing the play/pause control to start in the "playing" state when the autostart setting is set to false.

Version 1.4.2 — 12 May 2011

  • Fixed fatal bug introduced in previous update.
  • Improved image width detection to fix occasional image positioning bug in certain browsers.

Version 1.4.1 — 12 May 2011

  • Renamed the 'private' object to 'RssPrivateMethods' to avoid problems with the global namespace.
  • Tidy up of the code and correction of some minor errors.

Version 1.4 — 5 May 2011

  • Added the removeSlides() method.
  • Added the getSlideData() method.
  • Included QTest unit testing (for new methods only).

Version 1.3.1 — 2 May 2011

  • Fixed image size detection bug when resizing images using CSS.
  • Fixed bug causing controls to be auto-generated regardless of settings.
  • Private methods are no longer available publicly.
  • Moved all default options to $.rsfSlideshow.defaults

Version 1.3 — 1 May 2011

  • Added the controls option.
  • Changed the name of the eventCallbacks option to eventHandlers.
  • Changed the behaviour of the following methods: bindPlayPause(), bindPreviousSlide(), bindNextSlide() and bindIndex() so that they require jQuery objects to bind the behaviours to.
  • Changed the name of the bindNext() method to bindNextSlide().
  • Changed the name of the bindPrevious() method to bindPreviousSlide().
  • Removed the following options: play_pause_class, prev_class, next_class, stop_on_prev_next, index_class and stop_on_index.
  • Added auto-generation of control elements.

Version 1.2 — 27 Apr 2011

  • Added bindIndex() method as a quick way to create "go to slide..." control functionality.
  • Added bindPrevious() and bindNext() methods as a quick way to create prev/next control functionality.
  • Added bindPlayPause() method as a quick way to create play/pause control functionality.
  • Added the isRunning() method to determine whether the slideshow is running.
  • Added default event callbacks to options, to aid with setup of global slideshow functionality.
  • Added $.rsfSlideshow() method for setting options globally.
  • Added event triggers for slideshow events.

Version 1.1 — 18 Apr 2011

  • Added a minified version of the source.
  • Changed the name of the plugin file to jquery.rs.slideshow.js to bring it into line with jQuery plugin naming convention.
  • Bug fix: More consistent behaviour across browsers when loading cached images into a slideshow.
  • Changes to the default markup used for specifying slide data. Markup now makes more sense semantically, and offers the opportunity to allow non-JavaScript users to click on links to slideshow images. (Extra CSS is required to do this, and we'll publish this soon).
  • slide_data_selectors option added. This makes slide data more customisable.
  • url_data_selector option removed (replaced by slide_data_selectors).
  • caption_data_selector option removed (replaced by slide_data_selectors).
  • link_url_data_selector option removed (replaced by slide_data_selectors).
  • effect_data_selector option removed (replaced by slide_data_selectors).