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:
;
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:
;
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:
;
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:
;
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:
;
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 |
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.
roundabout
Starts the Roundabout.
Usage
Parameters
object |
options is an object of
options to configure how
Roundabout acts
|
function |
callback is a function
that is called once the Roundabout is ready
|
Returns a jQuery object.
setBearing
Changes the bearing
of the Roundabout.
Usage
Parameters
float |
bearing is a value
between 0.0 and 359.9
|
function |
callback is a function
that is called once the change completes
|
Returns a jQuery object.
adjustBearing
Alters the bearing
of the Roundabout by a given amount, either positive or negative degrees.
Usage
Parameters
float |
delta is the amount by
which the bearing will change
(either positive or negative)
|
function |
callback is a function
that is called once the change completes
|
Returns a jQuery object.
setTilt
Changes the tilt
of the Roundabout.
Usage
Parameters
tilt |
tilt is a value
typically between -2.0 and
10.0
|
function |
callback is a function
that is called once the change completes
|
Returns a jQuery object.
adjustTilt
Alters the tilt
of the Roundabout by a given amount, either in positive or negative mounts.
Usage
Parameters
tilt |
delta is the amount by
which the tilt will change
(either positive or negative)
|
function |
callback is a function
that is called once the change completes
|
Returns a jQuery object.
animateToNearestChild
Animates the Roundabout to the nearest child. This animation will not move the Roundabout if any child is already in focus.
Usage
Parameters
integer |
duration is the length
of time (in milliseconds) that the animation
will take to complete; uses Roundabout�s
configured duration if no value
is set here
|
string |
easing is the name of
the easing function to use for movement;
uses Roundabout�s configured easing
if no value is set here
|
function |
callback is a function
that is called once the change completes
|
Returns a jQuery object.
animateToChild
Animates the Roundabout to the given childPosition
, which is a zero-based counter of children based on the order of markup.
Usage
Parameters
integer |
childPosition is the
zero-based child to which Roundabout
will animate
|
integer |
duration is the length
of time (in milliseconds) that the animation
will take to complete; uses Roundabout�s
configured duration if no value
is set here
|
string |
easing is the name of
the easing function to use for movement;
uses Roundabout�s configured easing
if no value is set here
|
function |
callback is a function
that is called once the change completes
|
Returns a jQuery object.
animateToNextChild
Animates the Roundabout to the next child element.
Usage
Parameters
integer |
duration is the length
of time (in milliseconds) that the animation
will take to complete; uses Roundabout�s
configured duration if no value
is set here
|
string |
easing is the name of
the easing function to use for movement;
uses Roundabout�s configured easing
if no value is set here
|
function |
callback is a function
that is called once the change completes
|
Returns a jQuery object. Returns a jQuery object.
animateToPreviousChild
Animates the Roundabout to the previous child element.
Usage
Parameters
integer |
duration is the length
of time (in milliseconds) that the animation
will take to complete; uses Roundabout�s
configured duration if no value
is set here
|
string |
easing is the name of
the easing function to use for movement;
uses Roundabout�s configured easing
if no value is set here
|
function |
callback is a function
that is called once the change completes
|
Returns a jQuery object.
animateToDelta
Animates the Roundabout to the given amount of degrees away from its current bearing
(either positive or negative degrees).
Usage
Parameters
float |
degrees is the amount
by which the bearing will change
(either positive or negative)
|
integer |
duration is the length
of time (in milliseconds) that the animation
will take to complete; uses Roundabout�s
configured duration if no value
is set here
|
string |
easing is the name of
the easing function to use for movement;
uses Roundabout�s configured easing
if no value is set here
|
function |
callback is a function
that is called once the change completes
|
Returns a jQuery object.
animateBearingToFocus
Animates the Roundabout so that a given bearing
ends at the configured focusBearing
.
Usage
Parameters
float |
degrees is a value
between 0.0 and 359.9
|
integer |
duration is the length
of time (in milliseconds) that the animation
will take to complete; uses Roundabout�s
configured duration if no value
is set here
|
string |
easing is the name of
the easing function to use for movement;
uses Roundabout�s configured easing
if no value is set here
|
function |
callback is a function
that is called once the change completes
|
Returns a jQuery object.
startAutoplay
Starts the Roundabout�s autoplay
feature.
Usage
Parameters
function |
callback is a function
that is called after each autoplay
animation completes
|
Returns a jQuery object.
stopAutoplay
Stops the Roundabout�s autoplay
feature.
Usage
Parameters
boolean |
keepAutoplayBindings � when true �
will not destroy any autoplay mouseenter and mouseleave
event bindings that were set by autoplayPauseOnHover
|
Returns a jQuery object.
toggleAutoplay
Starts or stops the Roundabout�s autoplay
feature (based upon its current state).
Usage
Parameters
function |
callback is a function
that is called after each autoplay
animation completes
|
Returns a jQuery object.
isAutoplaying
Checks to see if the Roundabout�s autoplay
feature is currently playing or not.
Usage
Parameters
No parameters.
Returns a boolean.
changeAutoplayDuration
Changes the length of time (in milliseconds) that the Roundabout�s autoplay
feature waits between attempts to animate to the next child.
Usage
Parameters
integer |
duration is a length of
time (in milliseconds) between attempts to have
autoplay animate to the next child element
|
Returns a jQuery object.
relayoutChildren
Repositions child elements based on new contextual information. This is most helpful when the Roundabout element itself changes size and moving child elements within need readjusting.
Usage
Parameters
No parameters.
Returns a jQuery object.
getNearestChild
Gets the nearest child element to the focusBearing
. This number is a zero-based counter based on order of markup.
Usage
Parameters
No parameters.
Returns a integer.
getChildInFocus
Gets the child currently in focus. This number is a zero-based counter based on order of markup.
Usage
Parameters
No parameters.
Returns a integer.
Hookable Events
Roundabout is equipped to trigger events on both the Roundabout element itself and the moving child elements.
ready
This event fires on the Roundabout element once it and its child elements have been initialized. It also fires on each child element once it has been initialized.
focus
This event fires on child elements that land in the focusBearing
at the end of an animation. Will only fire if triggerFocusEvents
is set to true
.
blur
This event fires on child elements that move away from the focusBearing
at the start of an animation. Will only fire if triggerBlurEvents
is set to true
.
childrenUpdated
This event fires on the Roundabout element when its child elements have been repositioned and are in place.
reposition
This event fires on child elements that have been repositioned and are in place.
bearingSet
This event fires on the Roundabout element when its bearing
has been set.
moveClockwiseThroughBack
This event fires on moving child elements when an animation causes them pass through the point that is opposite (or 180�) from the focusBearing
in a clockwise motion.
moveCounterclockwiseThroughBack
This event fires on moving child elements when an animation causes them to pass through the point that is opposite (or 180�) from the focusBearing
in a counterclockwise motion.
animationStart
This event fires on the Roundabout element at the start of any animation.
animationEnd
This event fires on the Roundabout element at the end of any animation.
autoplayStart
This event fires on the Roundabout element when the autoplay
feature starts.
autoplayStop
This event fires on the Roundabout element when the autoplay
feature stops.