README.md

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.

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:

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.

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.

Option

Description

Data Type

Default

bearing

The starting direction in which Roundabout should
face relative to the focusBearing.

float

0.0

tilt

Slightly alters the calculations of moving elements.
In the default shape,
it adjusts the apparent tilt. Other shapes
will differ.

float

0.0

minZ

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
focusBearing.

integer

100

maxZ

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
focusBearing.

integer

280

minOpacity

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 focusBearing.

float

0.4

maxOpacity

The greatest opacity that will be assigned to a
moving element. This occurs when the moving element
is at the same bearing as the
focusBearing.

float

1.0

minScale

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
focusBearing.

float

0.4

maxScale

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
focusBearing.

float

1.0

duration

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.

integer

600

btnNext

A jQuery selector of page elements that, when
clicked, will trigger the Roundabout to animate to
the next moving element.

string

null

btnNextCallback

A function that will be called once the animation
triggered by a
btnNext-related
click has finished.

function

function() {}

btnPrev

A jQuery selector of page elements that, when
clicked, will trigger the Roundabout to animate to
the previous moving element.

string

null

btnPrevCallback

A function that will be called once the animation
triggered by a
btnPrev-releated
click has finished.

function

function() {}

btnToggleAutoplay

A jQuery selector of page elements that, when
clicked, will toggle the Roundabout’s autoplay state
(either starting or stopping).

string

null

btnStartAutoplay

A jQuery selector of page elements that, when
clicked, will start the Roundabout’s
autoplay feature
(if it’s currently stopped).

string

null

btnStopAutoplay

A jQuery selector of page elements that, when
clicked, will stop the Roundabout’s
autoplay
feature (if it’s current playing).

string

null

easing

The easing function to use when animating Roundabout.
With no other plugins, the standard jQuery easing
functions are available. When using the
jQuery easing plugin,
all of its easing functions will also be available.

string

"swing"

clickToFocus

When true, Roundabout will bring
non-focused moving elements into focus when they’re
clicked. Otherwise, click events won’t be captured
and will be passed through to the moving child
elements.

boolean

true

clickToFocusCallback

A function that will be called once the
clickToFocus
animation has completed.

function

function() {}

focusBearing

The bearing that Roundabout will use as the focus
point. All animations that move Roundabout between
children will animate the given child element to this
bearing.

float

0.0

shape

The path that moving elements follow. By default,
Roundabout comes with one shape, which is
lazySusan. When using Roundabout with the
Roundabout Shapes
plugin, there are many other shapes available.

string

"lazySusan"

debug

When true, Roundabout will replace the
contents of moving elements with information about
the moving elements themselves.

boolean

false

childSelector

A jQuery selector of child elements within the elements Roundabout
is called upon that will become the moving elements within
Roundabout. By default, Roundabout works on unordered lists, but it
can be changed to work with any nested set of child elements.

string

"li"

startingChild

The child element that will start at the Roundabout’s
focusBearing
on load. This is a zero-based counter based on the
order of markup.

integer

0

reflect

When true, reverses the direction in which
Roundabout will operate. By default, next
animations will rotate moving elements in a clockwise
direction and previous animations will be
counterclockwise. Using reflect will flip the two.

boolean

false

floatComparisonThreshold

The maximum distance two values can be from one
another to still be considered equal by Roundabout’s
standards. This prevents JavaScript rounding errors.

float

0.001

autoplay

When true, Roundabout will automatically advance the
moving elements to the next child at a regular
interval (settable as
autoplayDuration).

boolean

false

autoplayInitialDelayadded in v2.4

The length of time (in milliseconds) to delay the start of
Roundabout’s configured autoplay
option. This only works with setting autoplay to
true, and only on the first start of autoplay.

integer

0

autoplayDuration

The length of time (in milliseconds) between
animation triggers when a
Roundabout’s autoplay
is playing.

integer

1000

autoplayPauseOnHover

When true, Roundabout will pause
autoplay when the
user moves the cursor over the Roundabout container.

boolean

false

enableDrag

Requires event.drag
and
event.drop
plugins by
ThreeDubMedia.
Allows a user to rotate Roundabout be clicking and
dragging the Roundabout area itself.

boolean

false

dropDuration

The length of time (in milliseconds) the animation
will take to animate Roundabout to the appropriate
child when the Roundabout is “dropped.”

integer

600

dropEasing

The easing function to use when animating Roundabout
after it has been “dropped.” With no other plugins,
the standard jQuery easing functions are available.
When using the
jQuery easing plugin
all of its easing functions will also be available.

string

"swing"

dropAnimateTo

The animation method to use when a dragged Roundabout
is “dropped.” Valid values are next,
previous, or nearest.

string

"nearest"

dropCallback

A function that will be called once the dropped
animation has completed.

function

function() {}

dragAxis

The axis along which drag events are measured. Valid
values are x and y.

string

"x"

dragFactor

Alters the rate at which dragging moves the
Roundabout’s moving elements. Higher numbers will
cause the moving elements to move less.

integer

4

triggerFocusEvents

When true, a focus event will
be triggered on the child element that moves into
focus when it does so.

boolean

true

triggerBlurEvents

When true, a blur event will be
triggered on the child element that moves out of the
focused position when it does so.

boolean

true

responsiveadded in v2.1

When true, attaches a resize event onto the
window and will automatically relayout Roundabout’s
child elements as the holder element changes size.

boolean

false

Callable Methods

Roundabout does a lot on its own, but all of the methods it uses internally to perform actions are publicly usable as well. Manually calling these methods give even more control over how Roundabout functions.