JQSlider by MarcelloDiSimone

You can download this project in either zip or tar formats.

You can also clone the project with Git by running:

                             $ cd /path/to/your/project/js/libs $ git clone git://github.com/MarcelloDiSimone/jquery.jqslider jquery.jqslider

Building

To build the minified version of the plugin you need grunt.js. It's a javascript based build tool, similar to ant.

Grunt is based on node and so requires node to be installed. It's recommended to install grunt globally by running following command on your console

$ npm install -g grunt
All other dependencies of the build process are defined in the package.json and can be easily installed by: 
$ npm install
Now grunt is set up and you can run it by simply typing grunt: 
$ grunt

Grunt will create following directory structure:

    deploy/
        css/
            jquery.jqslider.css
            skins/
                debug/
                    jquery.jqslider.skin.css
                default/
                    images/
                        sprite.png
                    jquery.jqslider.skin.css
        js/
            jquery.jqslider.js

Setup

After the build process, you're ready to setup a basic version of the slider. All you need to do is to include JQuery, the default style, the jquery.jqslider script and the needed HTML markup. If you like to control the slider programaticly or you want to add your own conrol handlers somewhere else one the page, you can remove the handlers from the markup.

                            
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.6.1/jquery.min.js"></script> <link href="js/jquery.jqslider/css/jquery.jqslider.min.css" rel="stylesheet" /> <script src="js/jquery.jqslider/js/jquery.jqslider.min.js"></script> <div id="myslider" class="jqslider"> <div class="jqs-container"> <ul> <li> <!-- content --> </li> </ul> </div> <a href="#" class="jqs-handler-next jqs-handler"></a> <a href="#" class="jqs-handler-prev jqs-handler"></a> </div>

<script> var slider = $('#myslider').jqslider(); </script>

3 ways to configure

You can configure the plugin in the standard JQuery style by passing an object with key value pairs.

                             $('#myslider').jqslider({option:value});

Additionaly you can change the global configuration for all sliders on a page.

                             // for a single value JQSlider.defaults.option = value; // for more than one value JQSlider.defaults = $.extend(JQSlider.defaults,{ option: value });

Or if you want, add individual configuration to the HTML element itself by placing a JSON string into a data-options attribute. The configuration must be a valid JSON String. Internaly single-quotes are replaced by double quotes, so you don't need to break with your HTML code style, but you can also write double quotes or even entities if you like to. 

                            
<div id="slide2" class="jqslider jqs-vertical" data-options="{'option':'value'}"> <-- alternativly --> <div id="slide2" class="jqslider jqs-vertical" data-options='{"option":"value"}'> <-- alternativly --> <div id="slide2" class="jqslider jqs-vertical" data-options="{&quot;option&quot;:&quot;value&quot;}">

Configuration options

So what's there to configure anyway? Here we go. First off all the autoinit value.

@config {Boolean} autoinit
@default true

You can prevent an automatic initialisation of the slider. This is needed, for example if you want to bind a function to the init event (otherwise it would be triggered already). Another reason to do so is when you add new slides with the addSlide method and need to determin ie. the width or height of the newly created slide (after the init call all slides except of the current active one will be hidden and thus makes it hard to determin the right values). Let me know if you find other situations, where you need to use this approach, or if you see a posibility to avoid this workaround by a design change of the plugin. 
                             var slider = $('#my-slider').jqslider({autoinit:false}); // let's add a autoslide functionality slider.bind({ 'init mouseout':function(e){ var $this = $( this ); this.intID = setInterval( function () { $this.trigger( 'next' ); }, 5000 ); }, 'mouseover':function (e) { clearInterval( this.intID ); } }); // get the plugin class instance var sliderInstance = slider.data('jqslider'); sliderInstance.init();

Configuring the animation behaviour

@config {Boolean} circular
@default false

Set to true, for an infinite loop of slides.

@config {Number} duration
@default 500

Duration of the animation

@config {String} easingFunction
@default 'linear'

If you have included the easing plugin, you can define an easing function for the animation.

@config {Number} startSlide
@default 0

Zero based index of the slide to start with. Can also be set by adding the class jqs-current to the HTML element of the slide.

Configuring the markup

If you have rich content and normal lists don't fit your semantic needs, you can use whichever markup you like, and configure the selectors of the new elements with containerSelector, listSelector and slideTag. While you're able to define any selector jquery knows of for the container and list element, you must define a HTML tag for the slide element. This limitation is because new slides will be created with that tag. 

                            
<div id="myslider" class="jqslider"> <div class="jqs-container"> <article> <section> <!-- content --> </section> </article> </div> </div>

<script> var slider = $('#myslider').jqslider({ listSelector:'article', slideTag:'section' }); </script>

@config {String} containerSelector
@default '.jqs-container'

Define the jquery selector of the container element for querying. Must be set in the markup.

@config {String} listSelector
@default 'ul'

Define the jquery selector of the list element for querying.

@config {String} slideTag
@default 'li'

Define the tag name of the slide element for querying. It will be used for building the HTML template when creating a new slide.

Events to trigger

JQSlider is intended to be controlled by events. Although you're able to control it by accessing the plugin instance, it's designed to be event based. here are the events bound to the jqslider root element, you can trigger them to control the slider behaviour.

                             /** * @event next */ $('#my-slider').trigger('next'); /** * @event prev */ $('#my-slider').trigger('prev'); /** * @event gotoslide * @param {Number} slideNumber zero based index of the slide to go to * @param {Boolean} [counterwise=false] optional parameter, if the animation should move to the opposite direction * @param {Boolean} [noAnimation=false] optional parameter, if the slide should be shown instantly without an animation */ $('#my-slider').trigger('gotoslide', [1, true, false]);

Events to listen to

The plugin also triggers several events you can bind your functionality to.

                            var slider = $('#my-slider').jqslider({autosetup:false}) slider.bind({ 'init':function(){ /* called after initialisation of the plugin */ }, 'animationstart':function(){ /* called before every animation */ }, 'animationend':function(){ /* called after every animation */ } });

slider.find('.jqs-slide').bind({ 'animationinstart':function(){ /* triggered on the slide element before it is animated into the viewport */ }, 'animationinend':function(){ /* triggered on the slide element after it is animated into the viewport */ }, 'animationoutstart':function(){ /* triggered on the slide element before it is animated out of the viewport */ }, 'animationoutend':function(){ /* triggered on the slide element after it is animated out of the viewport */ } });

More Information

Check out the API Documentation

API Documentation

There are also some example files, you can find here: