a jQuery plugin by Fred LeBlanc
I’m a Roundabout!
Try Me Out.
← Click a box in the back. →Insane! :-O!
Amazing, eh?
Keep clicking.Try This:
Click & Drag Left/Right
And prepare to be amazed.And Yes,
It Works With Images
Whoa! :-O!
Awesome, right?
Keep clicking.
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 anextensive API that allows for some pretty amazing results.
Roundabout requires jQuery (at least version 1.2, successfully tested through version 1.7.2). It works in all major modern browsers and even some of the older, not-so-modern ones.
It’s open source and released under the BSD license, meaning that it’s free to use in your personal or commercial projects.
See Roundabout In Action
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.)
Learn
In an attempt to help all ranges of JavaScript & jQuery expertise-levels, I’ve constructed a couple of lessons to help you do some great things with Roundabout. I’ll be posting more as I have time to make them.
Your First Roundabout
Learn how to go from unordered-list to full-on Roundabout in just a couple easy steps.How to Use Roundabout Shapes
Roundabout can move in more ways than just a turntable. Find out how.Enabling Drag & Drop
Learn how to let users drag your Roundabout around instead of just clicking-to-focus.
Setting Options
Changing options is a simple way to customize Roundabout to fit your needs. Learn how.Calling Methods
Learn how to call internal methods on Roundabout to do things you couldn’t do before.Using Autoplay
Discover how to turn on autoplay and further customize how it works.
Support
New in V2
Roundabout has been completely rewritten from the ground up, with the goal of tackling a couple of known issues (v1, for example, would hang if you had a prime number of moving elements).
The code is also a lot cleaner and better commented, which will hopefully allow you to get in there and tweak if you want to.
Other New Things
- Autoplay is now built in
- Drag & Drop is now built in
- Many new options for even more control
- Many events and callbacks are now available
Upgrading from V1
Roundabout has changed the way its internal methods are called. It has been updated to use internal commands rather than many functions polluting the global scope.
If you were using any of the former roundabout_methods, version 2 will not by plug-and-play for you. However, getting things working should be quick and easy. Simply update any manual calls from this format…
$('ul').roundabout_animateToNextChild();
to this:
$('ul').roundabout('animateToNextChild');Issue Tracker
Note, the issue tracker is for version 2 issues only. Version 1 is no longer being supported.
Roundabout’s source code is now hosted over at GitHub, and the issue tracker has been opened up to record any bugs found. Review the list of reported bugs first, and if you’ve found something new, please add an issue.
Can You Please Help Me…
I present Roundabout to you in pretty good shape, but ultimately, it’s offered in as-is condition. That means that I can’t guarantee you support via email, although I will try to answer requests as I get them.
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 thefocusBearing. | 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 thefocusBearing. | 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’sautoplay feature (if it’s currently stopped). | string | null |
| btnStopAutoplay | A jQuery selector of page elements that, when clicked, will stop the Roundabout’sautoplay 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 thejQuery 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 theclickToFocus 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 Shapesplugin, 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 pauseautoplay when the user moves the cursor over the Roundabout container. | boolean | false |
| enableDrag | Requires event.drag and event.dropplugins 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.
roundabout
Starts the Roundabout.
Usage
.roundabout()
.roundabout(options)
.roundabout(callback)
.roundabout(options, callback)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 bearingof the Roundabout.
Usage
.roundabout("setBearing", bearing)
.roundabout("setBearing", bearing, callback)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
.roundabout("adjustBearing", delta)
.roundabout("adjustBearing", delta, callback)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
.roundabout("setTilt", tilt)
.roundabout("setTilt", tilt, callback)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 amounts.
Usage
.roundabout("adjustTilt", delta)
.roundabout("adjustTilt", delta, callback)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
.roundabout("animateToNearestChild")
.roundabout("animateToNearestChild", callback)
.roundabout("animateToNearestChild", duration, easing, callback)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
.roundabout("animateToChild", childPosition)
.roundabout("animateToChild", childPosition, callback)
.roundabout("animateToChild", childPosition, duration, easing)
.roundabout("animateToChild", childPosition, duration, easing, callback)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
.roundabout("animateToNextChild")
.roundabout("animateToNextChild", callback)
.roundabout("animateToNextChild", duration, easing)
.roundabout("animateToNextChild", duration, easing, callback)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.
animateToPreviousChild
Animates the Roundabout to the previous child element.
Usage
.roundabout("animateToPreviousChild")
.roundabout("animateToPreviousChild", callback)
.roundabout("animateToPreviousChild", duration, easing)
.roundabout("animateToPreviousChild", duration, easing, callback)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
.roundabout("animateToDelta", degrees)
.roundabout("animateToDelta", degrees, callback)
.roundabout("animateToDelta", degrees, duration, easing)
.roundabout("animateToDelta", degrees, duration, easing, callback)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 configuredfocusBearing.
Usage
.roundabout("animateBearingToFocus", degrees)
.roundabout("animateBearingToFocus", degrees, callback)
.roundabout("animateBearingToFocus", degrees, duration, easing)
.roundabout("animateBearingToFocus", degrees, duration, easing, callback)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’sautoplay feature.
Usage
.roundabout("startAutoplay")
.roundabout("startAutoplay", callback)Parameters
| function | callback is a function that is called after each autoplay animation completes |
Returns a jQuery object.
stopAutoplay
Stops the Roundabout’sautoplay feature.
Usage
.roundabout("stopAutoplay")
.roundabout("stopAutoplay", keepAutoplayBindings)Parameters
| boolean | keepAutoplayBindings — when true — will not destroy any autoplay mouseenter and mouseleave event bindings that were set byautoplayPauseOnHover |
Returns a jQuery object.
toggleAutoplay
Starts or stops the Roundabout’sautoplay feature (based upon its current state).
Usage
.roundabout("toggleAutoplay")
.roundabout("toggleAutoplay", callback)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’sautoplay feature is currently playing or not.
Usage
.roundabout("isAutoplaying")
Returns a boolean.
changeAutoplayDuration
Changes the length of time (in milliseconds) that the Roundabout’sautoplay feature waits between attempts to animate to the next child.
Usage
.roundabout("changeAutoplayDuration", duration)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
.roundabout("relayoutChildren")
Returns a jQuery object.
getNearestChild
Gets the nearest child element to thefocusBearing. This number is a zero-based counter based on order of markup.
Usage
.roundabout("getNearestChild")
Returns an integer.
getChildInFocus added in v2.2
Gets the child currently in focus. This number is a zero-based counter based on order of markup.
Usage
.roundabout("getChildInFocus")
Returns an 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 iftriggerFocusEvents 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.
Changes
For a more granular change-log, please follow along on GitHub.
- v2.4.1 – Fixed issue where responsive option was wreaking havoc with autoplay
- v2.4 – Fixed issue where Roundabout stopped working in jQuery v1.7.2.
- v2.3 – Added autoplayInitialDelay
- v2.2.1 – Fixed a bug where elements could not be added dynamically, fixed a responsive resize events issue
- v2.2 – Moved animationEnd to fire after the final bearing gets set on an animation, added getChildInFocus
- v2.1.1 – Fixed an issue where autoplayPauseOnHover was overriding a manually called stopAutoplay
- v2.1 – Added responsive
- v2.0 – Initial release
No comments:
Post a Comment