You can download this project in either a zip or tar format.
$ wget https://github.com/revolverjs/revolver-jquery/archive/v1.0.5.tar.gz
$ tar -zxvf revolver-jquery-1.0.5.tar.gz$ git clone git://github.com/revolverjs/revolver-jquery.gitLoad the jQuery plugin (or Mootools plugin) right after you load jQuery (or Mootools).
<script src="js/latest-jquery.min.js"></script>
<script src="js/jquery.revolver.min.js"></script><script src="js/latest-mootools.min.js"></script>
<script src="js/mootools.revolver.min.js"></script>As with any project, get yourself familiar with Revolver's API and common practices before diving in.
Go ahead, kick the tires! We're here if you need us! :)
Regardless of whether you are using jQuery or Mootools version of Revolver, there are only two ways to create a new instance.
The first method, and likely the most obvious, is to call it like a plugin. When using this method, the Revolver instance is stored in the element's storage for subsequent retrieval under the namespace "revolver".
$('#my_slider').revolver({options});
// get the instance
var my_slider = $('#my_slider').data('revolver');$('my_slider').revolver({options});
// get the instance
var my_slider = $('my_slider').retrieve('revolver');Or, if you're super cool and want to do it all in one line…
var my_slider = $('#my_slider').revolver({options}).data('revolver');var my_slider = $('my_slider').revolver({options}).retrieve('revolver');The second and more object-oriented method is to call the Revolver object like a constructor using the new keyword. When using this method, the Revolver instance is immediately returned.
// get the instance
var my_slider = new Revolver($('#my_slider'), {options});
// my_slider now contains the Revolver instance// get the instance
var my_slider = new Revolver($('my_slider'), {options});
// my_slider now contains the Revolver instanceIn some cases, you may need to extend (or even change) revolver in some way. Perhaps you want to create your own new transition, or maybe you need to change some of the default options... All of this is easily achievable by accessing the Revolver variable in the global scope.
// turn off autoPlay for all subsequent instances
Revolver.prototype.defaults.autoPlay = false;// Roll your own transition
Revolver.prototype.transitions.my_new_fancy_pants_transition = function() {
// code here
};
$('#my_slider').revolver({transition: {type: 'my_new_fancy_pants_transition'}});Holds the element that is wrapped around the slides.
$(document).ready(function(){
// setup revolver and get back the Revolver object
$('#my_slider').revolver();
var my_slider = $('#my_slider').data('revolver');
// get container
console.log(my_slider.container); // --> returns #my_slider element
});Each slide has a (zero-based) index number. For example, the first slide has an index of 0, the second has an index of 1, and so one. The currentSlide property returns the index number for the current slide.
$(document).ready(function(){
// setup revolver and get back the Revolver object
$('#my_slider').revolver();
var my_slider = $('#my_slider').data('revolver');
// get current slide's index number
console.log(my_slider.currentSlide); // --> returns 0
});The defaults property houses all the default options that revolver uses to merge your user-defined options upon instantiation. You may override this property to change the default options across the board.
$(document).ready(function(){
// get the default options
console.log(Revolver.prototype.defaults);
// turn off autoPlay for all subsequent instances
Revolver.prototype.defaults.autoPlay = false;
});To learn more about overriding properties, please read extending Revolver.
The dimensions property is used internally by Revolver to store the height and width of the slider.
This is used internally to disable all functionality within a Revolver instance.
This is the ID that Revolver uses to pause or kill playback.
The isAnimating property is equal to true if Revolver is currently animating, and false if not.
The iteration property is a running count of how many times Revolver has transitioned.
The lastSlide property will return the index key of the last slide in the slider.
The nextSlide property will return the index key of the next slide in the slider.
The numSlides is a count of the total number of slides that Revolver acting upon.
The options property is a congegation of all user-defined options and Revolver's default options.
The previousSlide property will return the index key of the slide that was last in transition (before the current one).
The slides property houses all the individual slides that Revolver is acting upon.
The status property will return the current status of the Revolver instance, whether it is "stopped", "paused", or "playing".
If you would like to know what version of Revolver is running, this is the one.
You can override Revolver's default optinos by passing your own custom options and callbacks as the first argument to the .revolver() plugin or as the second argument to the Revolver constructor.
Here's a quick snippet with all defaults declared so you can copy and paste into your project:
$('#my_slider').revolver({
autoPlay: true, // whether or not to automatically begin playing the slides
onReady: function(){}, // gets called when revolver is setup and ready to go
onPlay: function(){}, // gets called when the play() method is called
onStop: function(){}, // gets called when the stop() method is called
onPause: function(){}, // gets called when the pause() method is called
onRestart: function(){}, // gets called when the restart() method is called
rotationSpeed: 4000, // how long (in milliseconds) to stay on each slide before going to the next
slideClass: 'slide', // this is what revolver will look for to determin what is a slide
transition: {
direction: 'left', // which way to slide each slide. used for the 'slide' transition type only.
easing: 'swing', // default easing method
onStart: function(){}, // gets called when the transition animation begins
onFinish: function(){}, // gets called when the animation is done
speed: 500, // how long (in milliseconds) the transition should last
type: 'fade' // choose between none, fade, or slide
}
});
// or...
new Revolver($('#my_slider'), {
autoPlay: true, // whether or not to automatically begin playing the slides
onReady: function(){}, // gets called when revolver is setup and ready to go
onPlay: function(){}, // gets called when the play() method is called
onStop: function(){}, // gets called when the stop() method is called
onPause: function(){}, // gets called when the pause() method is called
onRestart: function(){}, // gets called when the restart() method is called
rotationSpeed: 4000, // how long (in milliseconds) to stay on each slide before going to the next
slideClass: 'slide', // this is what revolver will look for to determin what is a slide
transition: {
direction: 'left', // which way to slide each slide. used for the 'slide' transition type only.
easing: 'swing', // default easing method
onStart: function(){}, // gets called when the transition animation begins
onFinish: function(){}, // gets called when the animation is done
speed: 500, // how long (in milliseconds) the transition should last
type: 'fade' // choose between none, fade, or slide
}
});Please note that setting custom options does not overwrite Revolver's defaults, the new options are simply merged with the defaults and stored seperately, leaving the original defaults untouched for future use. If you want to change any of the defaults for all of your sliders, please check out the Extending Revolver section.
Set to false if you do not want Revolver to begin playing immediately.
// turn off autoPlay
$('#my_slider').revolver({autoPlay: false});This is called everytime the pause() method is called.
$('#my_slider').revolver({
onPause: function() {
// your code here
}
});Note: The this variable is equal to the Revolver object.
This is called everytime the play() method is called.
$('#my_slider').revolver({
onPlay: function() {
// your code here
}
});Note: The this variable is equal to the Revolver object.
This is called as soon as Revolver is completely setup and ready to go.
$('#my_slider').revolver({
onReady: function() {
// your code here
}
});Note: The this variable is equal to the Revolver object.
This is called everytime the restart() method is called.
$('#my_slider').revolver({
onRestart: function() {
// your code here
}
});Note: The this variable is equal to the Revolver object.
This is called everytime the stop() method is called.
$('#my_slider').revolver({
onStop: function() {
// your code here
}
});Note: The this variable is equal to the Revolver object.
The number of milliseconds to stay on each slide before transitioning to the next.
// speed up the slider to 1 second per slide
$('#my_slider').revolver({rotationSpeed: 1000});Since Revolver doesn't assume every child element in the container is a slide, it needs to know which elements are, in fact, a slide.
Assuming your HTML structure looks something like this:
<div id="top_news">
<img src="some_icon.png" alt="">
<h2 class="headline">How to make pure awesomeness with Revolver.js</h2>
<h2 class="headline">How to take your javascript skills to the next level</h2>
<h2 class="headline">Embrace prototypes, they're awesome!</h2>
</div>You're JS would look like this:
// use a custom class for my slides
$('#top_news').revolver({slideClass: 'headline'});The transition option is just a namespace for the options that are specific to the transition itself.
The direction the transition should take. Can be set to "up", "down", "left", or "right".
// let's slide up
$('#my_slider').revolver({
transition: {
type: 'slide',
direction: 'up'
}
});By default, there are only two easing methods available that's included in the jquery library: "swing" and "linear". To get more, go get the jquery easing plugin, include it in your document before Revolver, then replace "swing" with the name of the new easing method.
// use linear easing instead
$('#my_slider').revolver({
transition: {
easing: 'linear'
}
});This is called when the transition's animation is done.
$('#my_slider').revolver({
transition: {
onFinish: function() {
// your code here
}
}
});Note: The this variable is equal to the Revolver object.
This is called when the transition's animation has started.
$('#my_slider').revolver({
transition: {
onStart: function() {
// your code here
}
}
});Note: The this variable is equal to the Revolver object.
The number of milliseconds the transition (animation) should last.
// speed up the animation to 300 ms
$('#my_slider').revolver({
transition: {
speed: 300
}
});The type of transition to use for all transitions. See here for the full list of available transitions.
// use the "slide" transition
$('#my_slider').revolver({
transition: {
type: 'slide'
}
});These methods allow you to build the controls for your slider. You must call them off of the Revolver object, not the jQuery object. Since there is no enforced standard for getting and storing a plugin's object in jQuery, I decided to utilize jQuery's data method for this and bind the Revolver object to the slider's container. Here's how you would get the Revolver object after calling the plugin:
$(document).ready(function(){
// setup the slider the way you want it
// then get and save the revolver object for later
var revolver = $('#my_slider').revolver({transition: {type: 'slide'}}).data('revolver');
// now you can start binding these api methods to your controls
// for example:
$('a#goto_next_slide').click(function(event){
event.preventDefault(); // prevents browser from following the link
revolver.next(); // tells revolver to change to the next slide
});
});Transition immediately to the first slide, optionally passing temporary transition options.
<!-- my slider -->
<div id="my_slider">
<img class="slide" src="slide1.png">
<img class="slide" src="slide2.png">
<img class="slide" src="slide3.png">
</div>
<!-- my controls -->
<a href="#" id="goto_first">Slide to the first slide</a>
<a href="#" id="goto_first_custom">Fade to the first slide</a>$(document).ready(function(){
// setup revolver and get back the Revolver object
var revolver = $('#my_slider').revolver({transitions: {type: 'slide'}}).data('revolver');
// setup controls
$('#goto_first').click(function(e){
e.preventDefault();
revolver.first();
});
$('#goto_first_custom').click(function(e){
e.preventDefault();
revolver.first({type: 'fade'});
});
});window.addEvent('domready', function() {
// setup revolver and get back the Revolver object
var revolver = new Revolver($('my_slider'), {transitions: {type: 'slide'}});
// setup controls
$('goto_first').addEvent('click', function(e){
e.preventDefault();
revolver.first();
});
$('goto_first_custom').addEvent('click', function(e){
e.preventDefault();
revolver.first({type: 'fade'});
});
});Transition immediately to any given slide, optionally passing temporary transition options. The first argument, which is required, is the (zero based) index number of the slide. The second, completely optional argument is temporary transition options object.
<!-- my slider -->
<div id="my_slider">
<img class="slide" src="slide1.png">
<img class="slide" src="slide2.png">
<img class="slide" src="slide3.png">
</div>
<!-- my bullets -->
<ul id="bullets">
<li><a href="#" class="goto" data-slide-index="0">1</a></li>
<li><a href="#" class="goto" data-slide-index="1">2</a></li>
<li><a href="#" class="goto" data-slide-index="2">3</a></li>
</ul>$(document).ready(function(){
// setup revolver and get back the Revolver object
var revolver = $('#my_slider').revolver({transitions: {type: 'slide'}}).data('revolver');
// bind click events to all .goto elements in #bullets
$('#bullets .goto').click(function(e){
e.preventDefault();
// get the index from the data-slide-index attribute
var i = $(this).data('slide-index');
revolver.goTo(i);
});
});Transition immediately to the last (not previous) slide, optionally passing temporary transition options.
<!-- my slider -->
<div id="my_slider">
<img class="slide" src="slide1.png">
<img class="slide" src="slide2.png">
<img class="slide" src="slide3.png">
</div>
<!-- my controls -->
<a href="#" id="goto_last">Go to the last slide</a>$(document).ready(function(){
// setup revolver and get back the Revolver object
var revolver = $('#my_slider').revolver().data('revolver');
// setup controls
$('#goto_last').click(function(e){
e.preventDefault();
revolver.last();
});
});Transition immediately to the next slide, optionally passing temporary transition options.
<!-- my slider -->
<div id="my_slider">
<img class="slide" src="slide1.png">
<img class="slide" src="slide2.png">
<img class="slide" src="slide3.png">
</div>
<!-- my controls -->
<a href="#" id="goto_next">Next</a>$(document).ready(function(){
// setup revolver and get back the Revolver object
var revolver = $('#my_slider').revolver().data('revolver');
// setup controls
$('#goto_next').click(function(e){
e.preventDefault();
revolver.next();
});
});Stops the slider but remembers it's position.
<!-- my slider -->
<div id="my_slider">
<img class="slide" src="slide1.png">
<img class="slide" src="slide2.png">
<img class="slide" src="slide3.png">
</div>
<!-- my controls -->
<a href="#" id="pause">Pause</a>$(document).ready(function(){
// setup revolver and get back the Revolver object
var revolver = $('#my_slider').revolver().data('revolver');
// setup controls
$('#pause').click(function(e){
e.preventDefault();
revolver.pause();
});
});Creates a loop to transition to the next slide and a given interval. You can also pass temporary transition options to the first transition in the play cycle.
<!-- my slider -->
<div id="my_slider">
<img class="slide" src="slide1.png">
<img class="slide" src="slide2.png">
<img class="slide" src="slide3.png">
</div>
<!-- my controls -->
<a href="#" id="play">Play</a>$(document).ready(function(){
// setup revolver and get back the Revolver object
var revolver = $('#my_slider').revolver().data('revolver');
// setup controls
$('#play').click(function(e){
e.preventDefault();
revolver.play();
});
});Transition immediately to the previous slide, optionally passing temporary transition options.
<!-- my slider -->
<div id="my_slider">
<img class="slide" src="slide1.png">
<img class="slide" src="slide2.png">
<img class="slide" src="slide3.png">
</div>
<!-- my controls -->
<a href="#" id="goto_previous">Previous</a>$(document).ready(function(){
// setup revolver and get back the Revolver object
var revolver = $('#my_slider').revolver().data('revolver');
// setup controls
$('#goto_previous').click(function(e){
e.preventDefault();
revolver.previous();
});
});Queues up the first slide as the next one without forcing the transition.
<!-- my slider -->
<div id="my_slider">
<img class="slide" src="slide1.png">
<img class="slide" src="slide2.png">
<img class="slide" src="slide3.png">
</div>
<!-- my controls -->
<a href="#" id="reset">Reset</a>$(document).ready(function(){
// setup revolver and get back the Revolver object
var revolver = $('#my_slider').revolver().data('revolver');
// setup controls
$('#reset').click(function(e){
e.preventDefault();
revolver.reset();
});
});This is the functional equivalent to calling stop() and then play() consecutively. You can optionally pass temporary transition options through to the play() method.
<!-- my slider -->
<div id="my_slider">
<img class="slide" src="slide1.png">
<img class="slide" src="slide2.png">
<img class="slide" src="slide3.png">
</div>
<!-- my controls -->
<a href="#" id="restart">Restart</a>$(document).ready(function(){
// setup revolver and get back the Revolver object
var revolver = $('#my_slider').revolver().data('revolver');
// setup controls
$('#restart').click(function(e){
e.preventDefault();
revolver.restart();
});
});Stops the slider from transitioning to the next slide, and resets the slider.
<!-- my slider -->
<div id="my_slider">
<img class="slide" src="slide1.png">
<img class="slide" src="slide2.png">
<img class="slide" src="slide3.png">
</div>
<!-- my controls -->
<a href="#" id="stop">Stop</a>$(document).ready(function(){
// setup revolver and get back the Revolver object
var revolver = $('#my_slider').revolver().data('revolver');
// setup controls
$('#stop').click(function(e){
e.preventDefault();
revolver.stop();
});
});