Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
branch: develop
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 356 lines (217 sloc) 9.88 kb

Class: SlideShow {#SlideShow}

Extensible mid-level class that manages transitions of elements that share the same space, typically for slideshows, tabs, and galleries.

Demos

Implements:

Options, Events, Loop

SlideShow Method: constructor {#SlideShow:constructor}

Syntax:

var mySlideShow = new SlideShow(element[, options, noSetup]);

Arguments:

  1. element - (element) The string for an id of an element of an element reference.
  2. options - (object) See below
  3. noSetup - (boolean) Prevents the slideshow from initializing (useful for loading dynamic data before initializing)

Options:

  • delay - (number: defaults to 7000) Milliseconds between slide transitions.
  • transition - (string: defaults to crossfade) The transition animation for all slides.
  • duration - (number: defaults to 7000) Duration of the transition animation.
  • autoplay - (boolean: defaults to false) Calls play upon initialization.
  • dataAttribute - (string: defaults to data-slideshow) The element attribute from which to pull transition options.
  • selector - (CSS string: defaults to > *) The selector used to find the slides relative to the slideshow element.
  • initialSlideIndex = (number: defaults to 0) The index of the initial slide to be shown.

Events:

  • show - (function) The function to execute when a slide transition begins.
  • showComplete - (function) The function to execute when a slide transition finishes.
  • play - (function) The function to execute when the slide show starts playing.
  • pause - (function) The function to execute when the slide show pauses.
  • reverse - (function) The function to execute when the slideshow is reversed.

SlideShow Event: onShow {#SlideShow:onShow}

  • (function) Executes when a slide transition begins.

Signature

onShow(slideData)

Arguments

  • slideData - (object) An object containing slide data that looks like

Example

mySlideShow.addEvent('show', function(slideData){
  slideData.next.element; // the actual DOM element
  slideData.next.index; // the index of the element in the slideshow
  slideData.previous.element;
  slideData.previous.index;
});

SlideShow Event: onShowComplete {#SlideShow:onShowComplete}

  • (function) Executes when a slide transition ends.

Signature

onShowComplete(slideData)

Arguments

  • slideData - (object) An object containing slide data the same as onShow.

SlideShow Method: show {#SlideShow:show}

Transitions from one slide to another.

Syntax:

mySlideShow.show(what, [options]);

Arguments:

  1. what - (mixed) Accepts the following arguments:
    • string next - shows the next slide
    • string previous - shows the previous slide
    • number - the index of a slide to show
    • element - slide element to show
  2. options - (object) An object literal containing a duration and transition to use instead of what's already defined for the element, same format as the class options.

Returns:

This SlideShow instance.

Examples:

mySlideShow.show('next');
mySlideShow.show('previous');
mySlideShow.show(2); // index
mySlideShow.show($('some-slide')); // element reference

// change the duration and transition
mySlideShow.show('next', {
  duration: '4000',
  transition: 'pushLeft'
});

SlideShow Method: setup {#SlideShow:setup}

Called automatically in the constructor, unless the noSetup argument is provided. Initializes the slideshow, you can reinitialize on demand. Mostly useful when slides are dynamically added.

Syntax:

mySlideShow.setup([options]);

Arguments:

  1. options - (object) Same options as the constructor.

Returns:

This SlideShow instance.

Example:

mySlideShow.setup({
  delay: 5000
});

SlideShow Method: play {#SlideShow:play}

Auto-plays the slideshow on the options.delay.

Syntax:

mySlideShow.play();

Returns:

This SlideShow instance.

SlideShow Method: pause {#SlideShow:pause}

Pauses the auto-play.

Syntax:

mySlideShow.pause();

Returns:

This SlideShow instance.

SlideShow Method: reverse {#SlideShow:reverse}

Reverses the slideshow auto-play direction.

Example:

mySlideShow.play();
mySlideShow.reverse(); // going backward now
mySlideShow.reverse(); // going forward now

Returns:

This SlideShow instance.

SlideShow function: defineTransition {#SlideShow:defineTransition}

Adds a custom transition to the SlideShow class to be used in any instances.

Syntax:

SlideShow.defineTransition(name, function(data){
  // code
});

Signature:

function(data)
  • data.previous the previous slide element
  • data.next the next slide element
  • data.duration how long the transition should last
  • data.instance the instance of SlideShow

Example:

SlideShow.defineTransition('flash', function(data){
  // hide the "current" slide immediately
  data.previous.setStyle('display', 'none');

  // fade out the next slide immediately
  data.next.setStyle('opacity', 0);

  // fade the next slide in, creating a "flash" effect
  new Fx.Tween(data.next, {
    duration: data.duration,
    property: 'opacity'
  }).start(1);
});

Notes

When a transition starts:

  1. The previous slide's z-index is 1 so it's on top.
  2. The next slide's z-index is 0 so it's behind.
  3. All other slides have display:none
  4. When the duration is met, the previous slide will be reset to display: none, and all other styles wiped out, so you don't need to worry about removing styles you've changed during the transition.

SlideShow function: defineTransition {#SlideShow:defineTransition}

Same as defineTransition except that it takes an object map of transition names and functions.

Example:

SlideShow.defineTransitions({
  flash: function(){
    // code
  },
  'bounce-slide': function(){
    // code
  }
});

SlideShow property: current {#SlideShow:current}

Contains an element reference to the current slide.

Syntax:

slideshow.current

SlideShow property: index {#SlideShow:index}

Contains the index of the current slide. Useful when varying transitions dependent upon the current slide.

Syntax:

slideshow.index

SlideShow property: slides {#SlideShow:slides}

A collection of element references of all slides.

Syntax

slideshow.slides

Native: Element {#Element}

Custom Native to allow all of its methods to be used with any DOM element via the dollar function $.

Element method: playSlideShow {#Element:playSlideShow}

Element shortcut method to create a slideshow instance with this element.

Syntax:

$('slide-container').playSlideShow(options);

Arguments:

  1. options (object) - Same options as the constructor except autoplay will be ignored.

Element method: pauseSlideShow {#Element:pauseSlideShow}

Element shortcut method to pause a slideshow instance created with the playSlideShow method.

Syntax:

$('slide-container').pauseSlideShow();

Element storage: slideshow-index #{Element:slideshow-index}

Each slide has its index stored with it.

Syntax

element.retrieve('slideshow-index');

Deprecated

SlideShow Method: showNext {#Deprecated:showNext}

Deprecated, use show('next').

SlideShow Method: showPrevious {#Deprecated:showPrevious}

Deprecated, use show('previous').

SlideShow Method: resetOptions {#Deprecated:resetOptions}

Deprecated, use setup(options).

SlideShow function: add {#Deprecated:add}

Deprecated, use addTransition

SlideShow changelog {#SlideShow:changelog}

1.x -> 2.0

This release brings with it lots of new features, better performance, and less code, what more could you ask for?

  • [New] SlideShow.CSS, transitions and method to use CSS3 transitions
  • [Changed] showNext -> show('next')
  • [Changed] showPrevious -> show('previous')
  • [Changed] SlideShow.add -> SlideShow.defineTransition
  • [New] SlideShow.defineTransitions - define multiple transitions at once
  • [New] setup method initializes everything, reinitialize on-demand
  • [New] constructor takes a noSetup argument to prevent initializing everything
  • [New] dataAttribute option for which element attribute to parse
  • [New] selector option, select whichever elements you want instead of just immediate children
  • [Changed] data object is passed to defineTransition instead of several args
  • [New] Slide Elements now have slideshow-index stored with them
  • [New] index property containing index of the current slide
Something went wrong with that request. Please try again.