Revolver: A JavaScript repository from Wonderful

#Revolver slider

A jQuery content slider with built in, easy to customize transitions based on jQuery 1.6+.

#Requirements

Revolve requires jQuery 1.6+.

#Getting started

To get started, download the plugin, unzip it, and copy the files to your web application directory. Make sure that you include a copy of the jQuery library, and then add your copy of jquery.revolver.js:

<head>
    <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.7/jquery.min.js"></script>
    <script type="text/javascript" src="/revolver/jquery.revolver.js"></script>
</head>

Add the HTML for your new Revolver. The standard HTML that Revolver works with is a "wrapper" div with children elements that will be doing the revolving. For example:

<div id="revolver">
	<div class="revolver-slide">Revolver slide 1</div>
	<div class="revolver-slide">Revolver slide 2</div>
	<div class="revolver-slide">Revolver slide 3</div>
</div>

Give your slideshow some simple styles:

#revolver {
	background-color:#ccc;
	width:100%;
	height:500px;
}

.revolver-slide {
	background-color:#fff;
	width:100%;
	height:100%;
}

Finally, initialize Revolver with basic settings at the bottom of your page, like this:

<script>
$(document).ready(function() {
	$('#revolver').revolver({
		autoplay		: true,
		rotationDelay 	: 2000
	});
});
</script>

Voila.

#Set up controls

Revolver allows you to use HTML elements to control it's movements. For example, you can set up a button that tells Revolver to show the next slide when clicked:

<!-- basic Revolver structure -->
<div id="revolver">
	<div class="revolver-slide">Revolver slide 1</div>
	<div class="revolver-slide">Revolver slide 2</div>
	<div class="revolver-slide">Revolver slide 3</div>
</div>

<!-- Will play next slide when clicked -->
<a href="#" id="next-button">Show next</a>

<script>
$(document).ready(function() {
	$('#revolver').revolver({
		nextButton : '#next-button', // the class or ID of the "next" button
	});
});
</script>

You can also add a button that tells Revolver to show the previous slide when clicked by adding a simple configuration setting:

<div id="revolver">
	<div class="revolver-slide">Revolver slide 1</div>
	<div class="revolver-slide">Revolver slide 2</div>
	<div class="revolver-slide">Revolver slide 3</div>
</div>

<!-- will show previous slide when clicked -->
<a href="#" id="prev-button">Show previous</a>

<a href="#" id="next-button">Show next</a>

<script>
$(document).ready(function() {
	$('#revolver').revolver({
		nextButton : '#next-button',
		prevButton : '#prev-button', // the class or ID of the "previous" button
	});
});
</script>

Now that you have your "next" and "previous" buttons set up, you can set up "manual advance" buttons that tell Revolver to show specific slides. These elements also require a data-slide attribute in each, to indicate which slide they represent:

<div id="revolver">
	<div class="revolver-slide">Revolver slide 1</div>
	<div class="revolver-slide">Revolver slide 2</div>
	<div class="revolver-slide">Revolver slide 3</div>
</div>


<a href="#" id="prev-button">Show previous</a>

<!-- will advance Revolver to specific slides when clicked -->
<a href="#" class="manual-button" data-slide="1">Show slide 1</a>
<a href="#" class="manual-button" data-slide="2">Show slide 2</a>
<a href="#" class="manual-button" data-slide="3">Show slide 3</a>

<a href="#" id="next-button">Show next</a>

<script>
$(document).ready(function() {
	$('#revolver').revolver({
		nextButton 		: '#next-button',
		prevButton 		: '#prev-button',
		manualButton	: '.manual-button', // the class or ID of the "manual" button(s)
	});
});
</script>

#Transitions

Revolver comes with various built-in options for transitioning between slides. In addition, transitions can be further customized by choosing a "direction" - which adds vertical or horizontal motion to the animation:

Transition	Setting	Available directions
Fade In	fadeIn	left, right, none (default)
Fade Out	fadeOut	left, right, none (default)
Slide	slide	top, bottom, left, right (default)

You can set a transition type, transition direction, and transition duration by adding the following settings:

<script>
$(document).ready(function() {
	$('#revolver').revolver({
		transitionType			: 'fadeIn',
		transitionDir		: 'none',
		transitionDuration	: 1000, // 1000 = 1 second, 2000 = 2 seconds, etc.
	});
});
</script>

#Complete custom settings

If you'd like to customize your Revolver, you can pass it a set of configurable settings when you initialize it:

<script>
$(document).ready(function() {
	$('#revolver').revolver({
		autoplay			: true, // start revolving automatically. Default: true
		childrenEls			: 'div', // a jQuery pointer to indicate the children divs. Default: 'div'
		cropSlideshow		: true, // whether to hide the overflow of the parent container. Default: true
		debug				: false, // output debug messages in console. Default: false
		hideInactiveSlides	: true, // visibly hide slides when they aren't in focus. Default: true
		nextButton			: null, // a class or ID of an element. Default: null
		manualButton		: null, // a class or ID of an element. Default: null
		prevButton			: null, // a class or ID of an element. Default: null
		pauseOnHover		: true, // pause Revolver on mouseover. Default: true
		rotationDelay		: 2000, // milliseconds between revolutions. Default: 2000 (2 seconds)
		transitionType		: 'fadeIn', // transition type (fadeIn, slide). Default: 'fadeIn'
		transitionDir		: 'none', // transistion direction (top, right, bottom, left, none). Default: 'none'
		transitionDuration	: 1000, // how fast the transition should be in milliseconds. Default: 1000 (1 second)
		afterLoad			: function(data) {}, // called after Revolver is initialized
		afterChange			: function(data) {}, // called after each slide rotation
		beforeChange		: function(data) {} // called before each slide rotation
	});
});
</script>

autoplay	Whether or now Revolver should start automatically after successfully loading. Boolean; Default value: true
childrenEls	Children elements of the parent element. These elements will be turned into the slides. DOM, String; Default value: 'div'
cropSlideshow	Hide any part of the slides that extend beyond the boundaries of the slideshow parent. Boolean; Default value: true
debug	Output debug messages to the console. Boolean; Default value: false
hideInactiveSlides	Visibly hide slides when they aren't in focus. Boolean; Default value: true
nextButton	An Html element that will cause Revolver to progress forward when clicked. DOM, String, null; Default value: null
prevButton	An Html element that will cause Revolver to progress backward when clicked. DOM, String, null; Default value: true
pauseOnHover	Pause the rotation when the mouse is hovered on the parent element. Boolean; Default value: true
rotationDelay	The number of milliseconds before the next rotation begins. Number; Default value: 2000 (2 seconds)
transitionType	The rotation transition type ('fadeIn', 'slide') String; Default value: 'fadeIn'
transitionDir	The transition direction - different options available depending on the value of `transitionType` ('top', 'right', 'bottom', 'left', 'none') String; Default value: 'none'
transitionDuration	The number of milliseconds each transition will take to complete. Number; Default value: 1000 (1 second)
afterLoad	Callback function to be fired once Revolver has successfully completed initializing. Is passed internal variables. Function, String; Default value: (empty function)
afterChange	Callback function to be fired each time Revolver completes a rotation. Is passed internal variables. Function, String; Default value: (empty function)
beforeChange	Callback function to be fired before Revolver rotates to the next slide. Is passed internal variables. Function, String; Default value: (empty function)

#More Examples

###Changing the state of an element based on the current slide:

Often, it's required to change the state of an element on the page according to which slide is visible at the moment. For example, when using manual transition buttons (like the classic dots that a user can click on to choose which slide they see), it's necessary that the button change color to reflect an "active" or "inactive" state.

Combining Revolver with some basic CSS, here is how we can achieve this:

<!-- set up styles for inactive and active manual buttons -->
<style>
	.manual-button {
		background-color:#666666;
		color:#000000;
	}
	
	.manual-button.active {
		background-color:#000000;
		color:#ffffff;
	}
</style>

<div id="revolver">
	<div class="revolver-slide">Revolver slide 1</div>
	<div class="revolver-slide">Revolver slide 2</div>
	<div class="revolver-slide">Revolver slide 3</div>
</div>

<!-- will advance Revolver to specific slides when clicked -->
<a href="#" class="manual-button" data-slide="1">Show slide 1</a>
<a href="#" class="manual-button" data-slide="2">Show slide 2</a>
<a href="#" class="manual-button" data-slide="3">Show slide 3</a>

<script>
$(document).ready(function() {
	$('#revolver').revolver({
		manualButton	: '.manual-button', // the class or ID of the "manual" button(s)
		beforeChange	: function(data) {
			$('.manual-button').each(function() {
				if($(this).attr('data-slide') == data.currSlide) {
					$(this).addClass('active');
				}else{
					$(this).removeClass('active');
				}
			});
		}
	});
});
</script>

#Copyright

Licensed under the MIT license: http://www.opensource.org/licenses/mit-license.php

wndrfl/Revolver