Documentation

Instructions for setup, configuration and so on...

You can download individual files or use a package manager such as Bower or NPM.

Core files

Provider files (needed for animations)

With Bower

bower install desoslide

With NPM

npm install desoslide

In your HTML page:

<!-- jQuery library -->
<script src="js/jquery.min.js"></script>

<!-- desoSlide styles -->
<link href="css/jquery.desoslide.min.css" rel="stylesheet">

<!-- desoSlide core -->
<script src="js/jquery.desoslide.min.js"></script>

<!-- Animate, used for slides transition (if you set effect.provider to 'animate', it's the default value) -->
<link href="css/animate.min.css" rel="stylesheet">

<!-- Magic, used for slides transition (if you set effect.provider to 'magic') -->
<link href="css/magic.min.css" rel="stylesheet">

Summary

Load jQuery and desoSlide files (beware that the CSS file loads a sprite: ../img/desoslide_controls.png, be sure this path is correct).
Then it depends which effect you want to use for slides transition. By default 'animate' is set, so include animate.min.css. Or use 'magic' (see options), so include magic.min.css.

Once the pain is gone, create your thumbnails. The minimal markup for a thumb is:

<a href="image.jpg">
    <img src="image_thumb.jpg" alt="Image">
</a>

Easy? If you need, specify a caption and a link on your thumb:

<a href="image.jpg">
    <img src="image_thumb.jpg" alt="Image"
         data-desoslide-caption-title="Hi i'm an image"
         data-desoslide-caption-link="http://my-website.com">
</a>

Think about where you want that the slideshow is displayed. Create a container <div id="slideshow"></div> or use an existing one.

Go to the "Configuration" section to see overall options and how to call your slideshow.

Demo

View some examples on the demo page.

Here are the default options:

defaults = {
    thumbs:             null,             // An anchors (`<a>`) collection
    thumbEvent:         'click',          // What event to capture on thumbnail ('click', 'mouseover')
    imageClass:         'img-responsive', // Image class(es)
    auto: {
        load:           true,             // Preloading images
        start:          false             // Autostarting slideshow
    },
    first:              0,                // Index of the first image to show
    interval:           3000,             // Interval between each images
    effect: {
        provider:       'animate',        // Effect provider ('animate', 'magic')
        name:           'fade'            // Transition effect
                                          // 'animate': 'fade', 'flipX', 'flipY', 'fun', 'light', 'roll', 'rotate', 'rotateBig', 'sideFade', 'sideFadeBig', 'slide', 'random'
                                          // 'magic': 'foolish', 'perspective', 'puff', 'swap', 'swash', 'tin', 'twister', 'random'
    },
    overlay:            'always',         // How to show overlay ('always', 'hover', 'none')
    controls: {
        show:           true,             // Shows the player controls (prev/pause/play/next)
        keys:           false             // Able to control by using the keyboard shortcuts (left/space/right)
    },
    events: {
        onThumbClick:       null,             // On thumb click if thumbEvent: 'click'
        onThumbMouseOver:   null,             // On thumb mouseover if thumbEvent: 'mouseover'
        onImageShow:        null,             // On image show
        onImageShown:       null,             // On image shown
        onImageHide:        null,             // On image hide
        onImageHidden:      null,             // On image hidden
        onImageClick:       null,             // On image click
        onPrev:             null,             // On previous
        onPause:            null,             // On pause
        onPlay:             null,             // On play
        onNext:             null,             // On next
        onError:            null,             // On error
        onWarning:          null,             // On warning
        onSuccess:          null              // On success
    }
}

Call the plugin inside $(window).load(function() {}):

$(window).load(function() {

    $('#slideshow').desoSlide({
        thumbs: $('ul.thumbs li > a')
        // Or
        thumbs: $('#thumbs1, #thumbs2').find('li > a')
        // Or
        thumbs: $('a.thumb')
        // etc.
    });

});

Control the slideshow by using the player and/or your keyboard keys when controls.keys is set to true:

Press left to go to the previous slide.
Press space to switch between play and pause.
Press right to go to the next slide.

Interact with your slideshow after initialization. Use these public methods inside $(window).load(function() {}).

Rebuild

Rebuilding your slideshow:

// Re-initialize
$('#slideshow').desoSlide('rebuild');

Thumbs

Accessing to your thumbs:

// Get all thumbs (an array of objects)
var my_thumbs = $('#slideshow').desoSlide('getThumbs');

[
    {
        alt: 'Alt attribute found in thumb',
        caption_link: 'link', // data-desoslide-caption-link
        caption_title: 'title', // data-desoslide-caption-title
        src: 'image path'
    }, {
        ...
    }
]

// Get a specific thumb based on its index (an object)
var my_thumb = $('#slideshow').desoSlide('getThumbs', 1);

{
    alt: 'Alt attribute found in thumb',
    caption_link: 'link', // data-desoslide-caption-link
    caption_title: 'title', // data-desoslide-caption-title
    src: 'image path'
}

Effect

Dynamically change the transition effect. It returns the applied effect.

animate provider effects:

bounce, fade, flipX, flipY, fun, light, roll, rotate, rotateBig, sideFade, sideFadeBig, slide

magic provider effects:

foolish, perspective, puff, swap, swash, tin, twister

// Set a transition effect (remember to add the appropriate provider CSS file)
var effect = $('#slideshow').desoSlide('setEffect', {
    provider: 'magic',
    name: 'tin'
});

{
    provider: 'magic',
    name: 'tin'
}

// Set a random transition effect
var effect = $('#slideshow').desoSlide('setEffect', {
    provider: 'animate',
    name: 'random'
});

{
    provider: 'animate',
    name: 'sideFade' // a random effect
}

Disable transition effect

You want an instant transition? Well then use the following syntax. It's not necessary to include any provider CSS file.

// Set a 'none' effect
var effect = $('#slideshow').desoSlide('setEffect', 'none');

{
    provider: null,
    name: 'none'
}

Or directly from options:

effect: 'none'

Slides

Interacting with your slides:

// Pause the slideshow if started
$('#slideshow').desoSlide('pause');

// Play the slideshow if paused
$('#slideshow').desoSlide('play');

// Is the slideshow playing?
$('#slideshow').desoSlide('isPlaying'); // true/false

// Go to the previous slide
$('#slideshow').desoSlide('goPrev');

// Go to the next slide
$('#slideshow').desoSlide('goNext');

// Go to a specific slide (here the third)
$('#slideshow').desoSlide('goTo', 2);

Three ways to listen slideshow events.

Use the options with events.onEventName: function().
Use event handlers:
- stand-alone handlers
- all-in-one handler

// Stand-alone event handlers
$('#slideshow').on('thumbClick.desoslide', function() {
    // on thumbClick
});

$('#slideshow').on('thumbMouseOver.desoslide', function() {
    // on thumbMouseOver
});

$('#slideshow').on('imageShow.desoslide', function() {
    // on imageShow
});

$('#slideshow').on('imageShown.desoslide', function() {
    // on imageShown
});

$('#slideshow').on('imageHide.desoslide', function() {
    // on imageHide
});

$('#slideshow').on('imageHidden.desoslide', function() {
    // on imageHidden
});

$('#slideshow').on('imageClick.desoslide', function() {
    // on imageClick
});

$('#slideshow').on('prev.desoslide', function() {
    // on previous slide
});

$('#slideshow').on('pause.desoslide', function() {
    // on pause
});

$('#slideshow').on('play.desoslide', function() {
    // on play
});

$('#slideshow').on('next.desoslide', function() {
    // on next slide
});

$('#slideshow').on('error.desoslide', function() {
    // on error
});

$('#slideshow').on('warning.desoslide', function() {
    // on warning
});

$('#slideshow').on('success.desoslide', function() {
    // on success
});

// All-in-one events handler
$('#slideshow').on({
    'thumbClick.desoslide': function() {
        // on thumbClick
    },
    'thumbMouseOver.desoslide': function() {
        // on thumbMouseOver
    },
    'imageShow.desoslide': function() {
        // on imageShow
    },
    'imageShown.desoslide': function() {
        // on imageShown
    },
    'imageHide.desoslide': function() {
        // on imageHide
    },
    'imageHidden.desoslide': function() {
        // on imageHidden
    },
    'imageClick.desoslide': function() {
        // on imageClick
    },
    'prev.desoslide': function() {
        // on prev
    },
    'pause.desoslide': function() {
        // on pause
    },
    'play.desoslide': function() {
        // on play
    },
    'next.desoslide': function() {
        // on next
    },
    'error.desoslide': function() {
        // on error
    },
    'warning.desoslide': function() {
        // on warning
    },
    'success.desoslide': function() {
        // on success
    }
});

desoSlide works with AngularJS. I made a directive for you, see the angularjs folder.

IE 9+
Firefox 5+
Chrome
Opera
Safari

CSS3 transitions fallback

In case of CSS3 transitions are not supported, a fallback takes over and does a basic fade effect.

Sylvain

Developer

Jaoued

Designer

Documentation

Download

Setup

Summary

Demo

Configuration

Controls

Public methods

Rebuild

Thumbs

Effect

Disable transition effect

Slides

Events

AngularJS

Browser compatibility

CSS3 transitions fallback

Contributors

Sylvain

Jaoued