Roundabout

Note: Roundabout is no longer under active development. I've moved the documentation over here to support the exists plugin, but there are known issues and such that won't be fixed. Use at your own risk.

Roundabout is a jQuery plugin that easily converts unordered lists & other nested HTML structures into entertaining, interactive, turntable-like areas.

It’s ready-to-go straight out of the box, but if you want to get crazy, Roundabout is highly-customizable with an extensive API that allows for some pretty amazing results.

Roundabout requires jQuery (at least version 1.2).

Add-Ons

Roundabout is equipped to play nicely with a couple of other plugins if they’re made available.

• Roundabout Shapes by Fred LeBlanc Roundabout can move in more ways than just a turntable. With Shapes, you have many other ways you can move your content around the page.

• jQuery Easing by George McGinley Smith jQuery comes with two easing styles built in, but this plugin adds many, many more. Include this script and use any of its defined easing functions in your Roundabout animations.

• Event.drag & Event.drop by ThreeDubMedia In addition to rotating on click, Roundabout can also move by clicking and dragging on the Roundabout element itself. Include these scripts and turn on enableDrag.

But That’s Not All!

The list above is only a list of the plugins that have support baked in, but Roundabout will play nicely with many other plugins. (It’s up to you to integrate those yourself.)

Using Roundabout

Include the jquery.roundabout.js JavaScript file on your page after you include jQuery itself. Also, either link to the included CSS file, or copy the CSS styles from that file and paste them into your site's CSS file.

To activate Roundabout in its simplest form, you can do this:

$('ul').roundabout();

Of course, this will change all of your ul elements into Roundabouts, which probably isn't what you want, but you can easily change the selector to only target the elements you wish to convert

Setting Options

You can set options on Roundabout to change how it behaves. Do this by passing in an object of options into the main Roundabout call upon initialization, like so:

$('ul').roundabout({
    btnNext: ".next"
});

Incorporating Roundabout Shapes

If you're using the sister plugin Roundabout Shapes, be sure to include the jquery.roundabout-shapes.js file after you include the main Roundabout JavaScript file. Next, you'll select the shape as on of the options that you pass into Roundabout upon initialization:

$('ul').roundabout({
    btnNext: ".next",
    shape: "figure8"
});

Calling Roundabout Methods

Roundabout comes with a number of methods you can call to better control how it works. Calling those methods are done by re-calling roundabout on the element that Roundabout is already working on and passing in the name of the method to use as the first parameter. If the method requires other parameters, pass those in as subsequent parameters.

For example, instead of using the btnNext option, you can manually implement this yourself like this:

$('.btnNext', function(e) {
    e.stopPropagation();
    e.preventDefault();
    
    // this is the action
    $('ul#myRoundabout').roundabout('animateToNextChild');
    
    return false;
});

Enabling Drag & Drop

Lately it seems that this doesn't work as well as it once did. Not sure why, but you can still enable it. To do this, you'll need to grab v2 of the jquery.event.drag and jquery.event.drop plugins by ThreeDubMedia. Include them on your page after Roundabout is included.

Next, enable your Roundabout to use drag and drop like so:

$('ul').roundabout({
    enableDrag: true
});

Using Autoplay

Autoplay lets you have Roundabout automatically animate on an interval. This functionality is included with the Roundabout core, so no additional scripts are needed to get this working.

To enable autoplay, there are three options you can set:

$('ul').roundabout({
    autoplay: true,
    autoplayDuration: 5000,
    autoplayPauseOnHover: true
});

The first option, autoplay will turn on autoplay. The second, autoplayDuration is the length of time in milliseconds between animation triggers. The final option, autoplayPauseOnHover will force autoplay never to figure while the user has their cursor over the Roundabout itself.

Support

Version 2 (the current version) works reasonably well, although if you look in the issues you'll see a number of things that don't work for some people. As mentioned above, this plugin is no longer under active development. Feel free to continue submitting issues for others to see, but no further official action can be guaranteed at all.

API

Settable Options

Roundabout comes with many settable configuration options that let you customize how it operates.

<table> <thead> <tr> <th scope="col">Option</th> <th scope="col">Description</th> <th scope="col">Data Type</th> <th scope="col" class="default-value">Default</th> </tr> </thead> <tbody> <tr id="bearing"> <td class="option"><code>bearing</code></td> <td> The starting direction in which Roundabout should face relative to the <code>focusBearing</code>. </td> <td class="data-type">float</td> <td class="default-value"><code>0.0</code></td> </tr>

	<tr id="tilt">
		<td class="option"><code>tilt</code></td>
		<td>
			Slightly alters the calculations of moving elements.
			In the default <code>shape</code>,
			it adjusts the apparent <code>tilt</code>. Other shapes
			will differ.
		</td>
		<td class="data-type">float</td>
		<td class="default-value"><code>0.0</code></td>
	</tr>

	<tr id="minZ">
		<td class="option"><code>minZ</code></td>
		<td>
			The lowest z-index that will be assigned to a moving
			element. This occurs when the moving element is
			opposite of (that is, 180° away from) the 
			<code>focusBearing</code>.
		</td>
		<td class="data-type">integer</td>
		<td class="default-value"><code>100</code></td>
	</tr>

	<tr id="maxZ">
		<td class="option"><code>maxZ</code></td>
		<td>
			The greatest z-index that will be assigned to a
			moving element. This occurs when the moving element
			is at the same bearing as the 
			<code>focusBearing</code>.
		</td>
		<td class="data-type">integer</td>
		<td class="default-value"><code>280</code></td>
	</tr>

	<tr id="minOpacity">
		<td class="option"><code>minOpacity</code></td>
		<td>
			The lowest opacity that will be assigned to a moving
			element. This occurs when the moving element is
			opposite of (that is, 180° away
			from) the <code>focusBearing</code>.
		</td>
		<td class="data-type">float</td>
		<td class="default-value"><code>0.4</code></td>
	</tr>

	<tr id="maxOpacity">
		<td class="option"><code>maxOpacity</code></td>
		<td>
			The greatest opacity that will be assigned to a
			moving element. This occurs when the moving element
			is at the same bearing as the
			<code>focusBearing</code>.
		</td>
		<td class="data-type">float</td>
		<td class="default-value"><code>1.0</code></td>
	</tr>

	<tr id="minScale">
		<td class="option"><code>minScale</code></td>
		<td>
			The lowest size (relative to its starting size) that
			will be assigned to a moving element. This occurs
			when the moving element is opposite of (that is, 180°
			away from) the
			<code>focusBearing</code>.
		</td>
		<td class="data-type">float</td>
		<td class="default-value"><code>0.4</code></td>
	</tr>

	<tr id="maxScale">
		<td class="option"><code>maxScale</code></td>
		<td>
			The greatest size (relative to its starting size)
			that will be assigned to a moving element. This
			occurs when the moving element is at the same bearing
			as the
			<code>focusBearing</code>.
		</td>
		<td class="data-type">float</td>
		<td class="default-value"><code>1.0</code></td>
	</tr>

	<tr id="duration">
		<td class="option"><code>duration</code></td>
		<td>
			The length of time Roundabout will take to move from
			one child element being in focus to another (when an
			animation is triggered). This value acts as the
			default for Roundabout, but each animation action can
			be given a custom duration for that animation.
		</td>
		<td class="data-type">integer</td>
		<td class="default-value"><code>600</code></td>
	</tr>

	<tr id="btnNext">
		<td class="option"><code>btnNext</code></td>
		<td>
			A jQuery selector of page elements that, when
			clicked, will trigger the Roundabout to animate to
			the next moving element.
		</td>
		<td class="data-type">string</td>
		<td class="default-value"><code>null</code></td>
	</tr>

	<tr id="btnNextCallback">
		<td class="option"><code>btnNextCallback</code></td>
		<td>
			A function that will be called once the animation
			triggered by a
			<code>btnNext</code>-related 
			click has finished.
		</td>
		<td class="data-type">function</td>
		<td class="default-value"><code>function() {}</code></td>
	</tr>

	<tr id="btnPrev">
		<td class="option"><code>btnPrev</code></td>
		<td>
			A jQuery selector of page elements that, when
			clicked, will trigger the Roundabout to animate to
			the previous moving element.
		</td>
		<td class="data-type">string</td>
		<td class="default-value"><code>null</code></td>
	</tr>

	<tr id="btnPrevCallback">
		<td class="option"><code>btnPrevCallback</code></td>
		<td>
			A function that will be called once the animation
			triggered by a
			<code>btnPrev</code>-releated 
			click has finished.
		</td>
		<td class="data-type">function</td>
		<td class="defa