search

joelambert / Flux-Slider

CSS3 Animation based image transitions
http://www.joelambert.co.uk/flux
Other
1.42k stars 285 forks source link

readme

Flux Slider

Flux slider is a CSS3 animation based image transition framework, inspired in part by the fantastic Nivo Slider jQuery plugin.

Instead of the traditional Javascript timer based animations used by jQuery, Flux utilises the newer, more powerful CSS3 animation technology. Its in a fairly early/rough state at the moment but testing on the iPhone/iPad does appear to produce much smoother animations. Desktop performance (as with Nivo) is very smooth but the use of CSS3 enables us to produce some new effects that Nivo can’t, e.g. rotations.

The aim is to use hardware acceleration where possible to improve performance on less powerful devices, such as mobiles & tablets.

Known to work with

May/should also work for

Requirements

Flux requires a browser which supports CSS3 transformations and has been built to use either jQuery or Zepto.js as they share the same API. For mobile deployment Zepto is recommended due to its <5k deployment footprint.

Usage

Create HTML markup with the images you wish to use. You can also wrap images in a link if you need them to be clickable. For example:

<div id="slider">
    <img src="https://github.com/joelambert/Flux-Slider/raw/master/img/avatar.jpg" alt="" />
    <img src="https://github.com/joelambert/Flux-Slider/raw/master/img/ironman.jpg" alt="" title="Ironman Screenshot" />
    <a href="https://github.com/joelambert/Flux-Slider/blob/master/"><img src="https://github.com/joelambert/Flux-Slider/raw/master/img/imagewithlink.jpg" alt="" /></a>
    <img src="https://github.com/joelambert/Flux-Slider/raw/master/img/tron.jpg" alt="" />
</div>

Next instantiate Flux Slider:

$(function(){
    window.myFlux = new flux.slider('#slider');
});

Or, if you're using the provided jQuery widget then you can also do the following:

$(function(){
    window.myFlux = $('#slider').flux();
});

Note: If you plan to use the Zepto framework then the widget method won't work

A note on feature detection

Flux now makes use of Modernizr when available for feature detection. Flux does not require Modernizr but it will use it instead of the inbuilt code if it's loaded.

Note: If you have a need to initialise Flux before the $.ready() event (not recommended!) then you will need to use Modernizr for feature detection as the inbuilt code does not play well with an uninitialised DOM.

Configuration options

The constructor can also take an optional second parameter which is an object of key/value configuration options.

For example, to prevent autoplay and show a pagination control you would do the following:

$(function(){
    window.myFlux = new flux.slider('#slider', {
        autoplay: false,
        pagination: true
    });
});

Or with the jQuery widget:

$(function(){
    window.myFlux = $('#slider').flux({
        autoplay: false,
        pagination: true
    });
});

flux.slider API

The API functions work with both the native Javascript object and the jQuery widget. For example:

// Show next image using the bars3d transition (native Javascript object)
window.myFlux.next('bars3d');

or

// Show next image using the bars3d transition (jQuery widget)
window.myFlux.flux('next', 'bars3d');

Note: All the jQuery widget functions are chainable except those that return something specific, such as isPlaying() & getImage().

For more information on using jQuery widgets see the jQuery Doc's;

Play controls

Transport controls

Misc

Receiving notification when a transition completes

There are occasions where you may wish to know when a transition has completed, or that the currently displayed image has changed.

Flux provides a couple of mechanisms for this:

fluxTransitionEnd Javascript Event

After each transition, Flux dispatches a fluxTransitionEnd event. To listen for these events you can do the following:

$('#slider').bind('fluxTransitionEnd', function(event) {
    var img = event.data.currentImage;
    // Do something with img...
});

onTransitionEnd callback function

You can alternatively pass in a callback function as part of the configuration options when you instantiate Flux, e.g.

window.myFlux = $('#slider').flux({
    autoplay: false,
    pagination: true,
    onTransitionEnd: function(data) {
        var img = data.currentImage;
        // Do something with img...
    }
});

Writing custom transitions

Writing your own custom transitions is easy, you just need to create an instance of a flux.transition object and pass in some callback functions to provide the custom behaviour you're looking for.

Lets look at the built in bars transition as an example. The barebones definition of the transition looks like:

flux.transitions.bars = function(fluxslider, opts) {
    return new flux.transition(fluxslider, $.extend({
        barWidth: 60,
        setup: function() {

        },
        execute: function() {

        }
    }, opts));  
}

Here we add a new function to the flux.transitions namespace called bars. This function takes two parameters, a flux.slider object and an options key/value object.

Note: Its currently not possible to pass options into transitions from the core flux.slider code but as this is on the list of things to add its a good idea to make sure the transitions can handle this when its implemented!

The function we create should return a new flux.transition object, passing in the flux.slider parameter along with a set of options.

All transition objects automatically have access to the following:

setup()

Two functions are needed for the transition to operate, first is setup. This function is responsible for initialising the DOM before the transition runs. In the case of the bars transition this function creates a div for each bar and set the background image so that adjacent bars appear as a single image.

The setup function should also initialise the CSS3 properties needed to enable a CSS transition.

setup: function() {
    var barCount = Math.floor(this.slider.image1.width() / this.options.barWidth) + 1

    var delayBetweenBars = 40;

    for(var i=0; i<barCount; i++) {
        var bar = $('<div></div>').attr('class', 'bar bar-'+i).css({
            width: this.options.barWidth+'px',
            height: '100%',
            position: 'absolute',
            top: '0',
            left: (i*this.options.barWidth)+'px',

            'background-image': this.slider.image1.css('background-image'),
            'background-position': '-'+(i*this.options.barWidth)+'px 0px'
        }).css3({
            'transition-duration': '400ms',
            'transition-timing-function': 'ease-in',
            'transition-property': 'all',
            'transition-delay': (i*delayBetweenBars)+'ms'
        });
        this.slider.image1.append(bar);
    }
}

A helper function called .css3() has been created for convenience to automatically add vendor prefixes to CSS3 properties. Any properties that require prefixes should be added via this function rather than .css() as this ensures that transitions are cross-browser compatible.

execute()

The execute function is where the CSS changes should be made, as transitions have already been initialised in setup() applying the end CSS property state should be all thats required:

execute: function() {
    var _this = this;

    var height = this.slider.image1.height();

    var bars = this.slider.image1.find('div.bar');

    // Get notified when the last transition has completed
    $(bars[bars.length-1]).transitionEnd(function(){
        _this.finished();
    });

    bars.css({
        'opacity': '0.5'
    }).css3({
        'transform': flux.browser.translate(0, height)
    });
}

Two further convenience functions have been used in this example. The first .transitionEnd() is a cross-browser event function to catch the 'transition end' event. In this example we want to be notified when the final bar as finished animating, this is how we know the transition is complete. We can then perform some custom code but its important to remember to call the transitions finished() function to ensure that the DOM is reset for the next transition.

Transition writing guidelines

Here are some guidelines for writing transitions if you'd like to have them considered for inclusion into the main distribution:

flux.browser

flux.browser is an object designed to help determine browser support for CSS3 transitions.

License

Flux is Copyright © 2011 Joe Lambert and is licensed under the terms of the MIT License.