Documentation

Instructions for setup, configuration and so on...

Documentation covers: 2.1.0

You can download individual files or use Bower for automatic download.

With Bower

bower install desoslide

All files are downloaded in the bower_components folder.

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

  1. You have to load jQuery and desoSlide files (beware that the CSS file loads a sprite: ../img/desoslide_controls.png, be sure this path is correct).
  2. 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.

Demo

View some examples on the demo page.

Here are the default options:

defaults = {
    thumbs:             null,             // An anchors (`<a>`) collection
    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
        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 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 initialize. 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
var my_thumbs = $('#slideshow').desoSlide('getThumbs');
[
    0: {
        alt: 'Alt attribute found in thumb',
        caption_link: 'link', // data-desoslide-caption-link
        caption_title: 'title', // data-desoslide-caption-title
        src: 'image path'
    },
    1: {
        ...
    }
]
// Get a specific thumb based on its index
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.

// 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.

// 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('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
    },
    '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

Sylvain

Developer

Sylvain

Jaoued

Designer