Really Simple™ Slideshow

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