Adaptor, a jQuery 3D content slider

Adaptor is a light-weight, responsive content slider that aims to provide a simple interface for developers to create cool 2D or 3D slide animation transitions.

Support

3D animations are implemented using CSS3 transforms and are therefore only supported by the browsers which support these. For browsers that do not support 3D transforms the 2D alternative will be used in it's place allowing for a graceful fallback.

Usage

Create a view port for the 3D perspective and within that add the HTML to create a box containing slides of content.

<div class="slider-viewport"><!-- works as a viewport for the 3D transitions -->
  <div id="content-box"><!-- the 3d box -->
    <figure class="jbs-current"><!-- slide -->
      <img src="img/slide-1.png">
      <figcaption>This is slide one's description</figcaption>
    </figure>
    <figure>
      <img src="img/slide-2.png">
      <figcaption>This is slide two's description</figcaption>
    </figure>
    <figure>
      <img src="img/slide-3.png">
      <figcaption>This is slide three's description</figcaption>
    </figure>
    <figure class="slide">
      <img src="img/slide-4.png">
      <figcaption>This is slide four's description</figcaption>
    </figure>
  </div>
</div>

Technically no CSS is required for the plugin to work but if the outer box, div.slider-viewport in this example, is statically positioned the plugin will apply relative positioning to it so that it can hold the positioned box.

Include the required build of the plugin with desired effect in your page and on page load apply the plugin to the content box with the desired options.

$('#content-box').boxSlider( /* options */ );

Options

• responsive (default: true) Tells the plugin to listen for page size changes and adapt the box to fit the screen
• speed (default: 800) The time interval in milliseconds within which the slide animation will complete
• autoScroll (default: false) Set true to automatically transition through the slides
• timeout (default: 5000) The time interval between slide transitions. For use with autoscroll
• pause (default: null) A DOM element, jQuery object or selector for an element that when clicked will toggle the autoscoll state of the slider. When the slider is in a paused state the element will be applied a class name of paused
• pauseOnHover (default: false) Pause an auto-scrolling slider when the users mouse hovers over it. For use with autoscroll
• next (default: null) A DOM element, jQuery object or selector for an element that when clicked will advance the slider to the next slide
• prev (default: null) A DOM element, jQuery object or selector for an element that when clicked will advance the slider to the previous slide
• effect (default: 'scrollVert3d') The slide animation effect to use when scrolling through content slides

Effect options

srollVert3d,scrollHorz3d

• perspective (default: 1000) The 3D perspective at which the content slides are placed from the view port during transition

tile3d,tile

• rowCount (default: 5) The number of tile rows into which the slide should be split
• rowOffset (default: 100) The time offset for starting to animate the tiles in a row

blindLeft,blindDown

• blindCount (default: 10) The number of blinds into which the slide should be split

Methods

showSlide

Shows a slide at the specified index starting from 0

$('#content-box').boxSlider('showSlide', 3); // show 4th slide

playPause

Start autoScrolling a slideshow or pause an already running slideshow

$('#content-box').boxSlider('playPause');

option

Get or set a specific option

$('#content-box').boxSlider('option', 'speed'); // returns speed option value
$('#content-box').boxSlider('option', 'speed', 1200); // sets the speed option to 1200

destroy

Destroys the plugin for the selected sliders

$('#content-box').boxSlider('destroy');

next

Moves the slider to the next slide

$('#content-box').boxSlider('next');

prev

Moves the slider to the previous slide

$('#content-box').boxSlider('prev');

Events

onbefore

Fires before each slide transition starts. The function parameter will be bound to the jQuerified box and will receive the current slide as it's first parameter, the next slide as its second, the current slide index as it's third and the next slide index as it's last.

$('#content-box').boxSlider('option', 'onbefore', function ($currentSlide, $nextSlide, currIndex, nextIndex) {
  // 'this' is effectively $('#content-box')
});

onafter

Fires after each slide transition is complete. The function parameter will be bound to the jQuerified box and will receive the previous slide as it's first parameter, the next slide as its second, the current slide index as it's third and the next slide index as it's last.

$('#content-box').boxSlider('option', 'onafter', function ($previousSlide, $currentSlide, currIndex, nextIndex) {
  // 'this' is effectively $('#content-box')
});

onplaypause

Fires when the play/pause state of the slideshow is changed. The function parameter will be bound to the jQuerified box and will receive the state of the slideshow as it's only parameter play|pause.

$('#content-box').boxSlider('option', 'onplaypause', function (state) {
  // 'this' is effectively $('#content-box')
});

Effects

The animation effects come as adaptors that are registered with the main box slider plugin using the registerAnimator method in one of the following ways. If the adaptor supports more than one animation effect then these must be passed in as a comma separated list.

$.fn.boxSlider('registerAnimator', 'effectName', AnimatorObject); // on $.fn
window.jqBoxSlider.registerAnimator('effect1,effect2' AnimatorObject); // on the global alias

Slide animators must implement the following interface and adhere to some fundamental rules.

configure(Boolean supports3D, String vendorPrefix)

This method is optional and is called during the adaptor registration process. The supports3D parameter identifies whether the host browser supports 3D CSS transformations and the vendorPrefix parameter provides the host browser CSS vendor prefix if it exists, e.g '-moz-', '-webkit-'.

adaptor.configure = function (supports3D, vendorPrefix) {
  // implementation omitted
};

initialize(jQuery $box, jQuery $slides, Object settings)

This method is required and sets up the initial state of each content slider. The first parameter $box is the jQuery content sliders main box (the selected element when the plugin is initialised), the second parameter is the jQuery $slides object containing all of the individual slide elements and the third parameter settings is the settings for the current content slider.

adaptor.initialize = function ($box, $slides, settings) {
  // implementation omitted
};

During the initialisation process you may set the _slideFilter attribute on settings which will be used to filter the set of slides ($slides) before the transition takes place. An example of this can be seen in the box-slider-fx-blinds.js adaptor. This filter uses the jQuery filter method but if you pass a function then that function will be bound to the unfiltered $slides jQuery object and will recieve the index as the first paramter and the plugin settings as the second.

adaptor.initialize = function ($box, $slides, settings) {
  // implementation omitted

  settings._slideFilter = function (index, settings) {
    return this.get(index) !== settings.$blinds; // 'this' will be $slides
  }
};

transition(Object settings)

This method is required and completes the transition from the current slide to the next slide. The settings parameter is the plugin settings for the content slider extended with the following.

{
    $box: // jQuery object containing the content slider box
  , $slides: // jQuery object containing all of the content slides
  , $currSlide: // jQuery object containing the current visible slide
  , $nextSlide: // jQuery object containing the next slide to show
  , reverse: // the direction in which to travel (read forwards, backwards)
  , currIndex: // the index at which $currSlide resides within $slides
  , nextIndex: // the index at which $nextSlide resides within $slides
}

This method must support browsers that do not support 3D transformations by degrading gracefully to some other method of transitioning the slides. Any settings that need to be cached against the content slider for the next transition should be returned as a simple object which will be mixed into the plugin settings.

adaptor.transition = function (settings) {
  // move to the next previous slides
  return { mycustomsetting: 'value' };
};

reset(jQuery $box, Object settings)

This method is optional and provides a method to reset the state of the plugin when an option is updated or the plugin is re-initialised. The first parameter $box is the content slider and the second settings is the options for the content slider.

adaptor.reset($box, settings) {
  // reset the content slider's state
}

destroy(jQuery $box, Object settings)

This method is required and handles the clean up required to return the element contained in the $box jQuery object back to it's original state before initialize was called. Any additional settings applied to settings should also be removed.

adaptor.destroy = function ($box, settings) {
  // reset css and remove any additional settings
};

_cacheOriginalCSS(jQuery $el, String name, Object settings, Array extraAttributes)

You do not need to define this method as it will be applied to the animation adaptor at the time it is registered with the plugin through the call to registerAnimator. This method will cache the original CSS of the given jQuery object in the bssettings data set for the slider, the settings object passed to all of the adaptor functions, so that the original CSS may be applied when the plugin is destroyed or reset. By default the following CSS attributes are cached position, top, left, display, overflow, width, height. Any additional attributes should be passed in as an array or strings in the extraAttributes parameter.

adaptor.initialize = function ($box, $slides, settings) {
  // cache the original css for reset or destroy
  adaptor._cacheOriginalCSS($box, 'box', settings);
  adaptor._cacheOriginalCSS($slides, 'slides', settings, [
      vendorPrefix + 'transform'
    , vendorPrefix + 'transition'
  ]);

  // implementation omitted
}

The cached CSS will then be available on the slider settings via the origCSS object under the item name provided when _cacheOriginalCSS was called.

adaptor.destroy = function ($box, settings) {
  // reset the original css
  $box.children().css(settings.origCSS.slides);
  $box.css(settings.origCSS.box);
};

Example adaptor

Below is an example of a simple 2D fade transition registered with the plugin as the fade effect.

;(function (w, $, undefined) {

  w.jqBoxSlider.registerAnimator('fade', (function () {

    var adaptor = {};

    // setup slide and box css
    adaptor.initialize = function ($box, $slides, settings) {
      // cache the original css for reset or destroy
      adaptor._cacheOriginalCSS($box, 'box', settings);
      adaptor._cacheOriginalCSS($slides, 'slides', settings);

      if ('static auto'.indexOf($box.css('position')) !== -1) {
        $box.css('position', 'relative');
      }

      $box.css({height: $slides.eq(0).height(), overflow: 'hidden'});
      $slides
        .css({ position: 'absolute', top: 0, left: 0 })
        .filter(':gt(0)').hide();
    };

    // fade current out and next in
    adaptor.transition = function (settings) {
      settings.$nextSlide.fadeIn(settings.speed);
      settings.$currSlide.fadeOut(settings.speed);
    };

    // reset the original css
    adaptor.destroy = function ($box, settings) {
      $box.children().css(settings.origCSS.slides);
      $box.css(settings.origCSS.box);
    };

    return adaptor;

  }()));

}(window, jQuery || Zepto));