Instantiable carousel widget that supports a variety of carousel formats: 1 up, many up, grouped slides, with or without navigation, infinite or finite, auto rotation, optional before/after slide change functions, easily overwriteable animation functions.
The carousel is structured as a long block element that slides back and forth inside a container with overflow: hidden. You can overwrite the _animateSlide
method of the prototype to use a different transition than the sliding movement.
When the infinite flag is set to true, the setup of the carousel elements changes to accomodate. Slides are duplicated from the beginning and end of the carousel and placed at the opposite ends. The number of slides duplicated on either end is equal to options->visibleItems.
If a user navigates to the end of the carousel and clicks 'next', the slider will transition past the end of the carousel and onto the duplicate beginning slides placed at the end during the setup. Once the animation is finished, the slider will instantly snap to the position of the 'real' slides at the beginning. Navigating backwards in the carousel to the beginning will work the same way, in reverse.
When working with slide indexes in the optional before/after slide change functions, the index will count any duplicate slides added to the beginning. A getVirtualSlideIndex
method is provided to get a 'real' slide index, without the duplicate slides from the infinite functionality. The duplicate slides also mean that the duplicate slides will have a twin, so if the content of those particular slides is being manipulated, you may have to do the manipulation in two places. Generally, trying to do anything really sophisticated with an infinite carousel is a challenging.
var myCarousel = new Carousel($('#slideList'), {options});
http://cemckinley.github.io/carousel/
- jQuery 1.7 or later
- jQuery easing, for default transitions. Can specify a basic transition in options > slideEasing if you don't want to include the easing plugin.
Type: Integer
Default: 1
Number of slides you want visible at a time
Type: Integer
Default: 400
Width in pixels of each slide. List items will be resized to fit.
Type: Integer
Default: 250
Height in pixels of each slide. List items will be resized to fit.
Type: Integer
Default: 10
Spacing in pixels between each slide
Type: String
Default: carouselWrapper
Class applied to a div created to wrap all carousel dom elements
Type: String
Default: carouselNavWrapper
Class applied to wrapping div for carousel navigation elements, if pagination was built automatically by widget
Type: Boolean
(or a jQuery Object
for a list) Default: true
Generates pagination elements (numbered/individual slide buttons) if true, or uses the jQuery list element passed in (list items in the list should relate to list items in the carousel, if using a custom list element). Adds event handlers for either. If false, no pagination.
Type: String
Default: carouselPagination
Class added to <ol>
element of the pagination, if pagination generated by the widget (where pagination: true
)
Type: Boolean
Default: true
If multiple slides are visible at the same time, should they be considered a 'group' for the pagination functionality? (e.g., one pagination button corresponds to one 'group', instead of an individual slide)
Type: Integer
Default: 400
Speed in milliseconds for slide change animation
Type: String
Default: easeOutExpo
Easing function to use for slide change animation
Type: Function
Default: null
Args: curSlideIndex
, newSlideIndex
, callback
Optional synchronous function that will be called at the beginning of the slide change action, before the carousel animation. The function is passed 3 arguments: the previous slide index, the new slide index, and the callback function that should be called synchronously to continue the command chain of the carousel change actions.
The context of 'this' will be the carousel instance, unless modified in the assignment with a bind method.
Example:
beforeSlideChange: function(curIndex, newIndex, callback){
this.slides.eq(curIndex).find('img').fadeOut(300);
this.slides.eq(newIndex).find('img').fadeIn(300);
callback();
}
Type: Function
Default: null
Args: oldSlideIndex
, newSlideIndex
Optional callback function that will be called after all other slide change actions have finished. The function is passed 2 arguments: the previous slide index, and the new slide index.
The context of 'this' will be the carousel instance, unless modified in the assignment with a bind method.
Example:
afterSlideChange: function(oldIndex, newIndex){
this.slides.eq(newIndex).find('video').play();
}
Type: Boolean
Default: true
If true, previous and next buttons will be generated for the carousel and click handlers added.
Type: String
Default: carouselBtnPrev
Class added to previous button element
Type: String
Default: carouselBtnNext
Class added to next button
Type: Boolean
Default: false
Flag to loop carousel infinitely when the first or last slide is reached. Setting to 'true' modifies the way the carousel is structured, to provide the infinite illusion. Slides from the beginning of the carousel and from the end of the carousel, in the amount of options>visibleSlides, are duplicated and added to the opposite end
Type: Boolean
Default: false
If true, Prev/Next buttons will be visible even when the number of slides is less than the amount of options>visibleItems. Normally, if there are not enough slides to require navigation, the prev/next buttons would not be rendered.
Type: Boolean
Default: false
Only allowed if options>infinite is set to true. Carousel will auto-navigate through slides on a set interval if set to true
. The interval stops once a user interacts with the carousel navigation, and pauses while the window or tab is inactive.
Type: Integer
Default: 7000
Millisecond delay between slide change actions for the auto rotation interval.
####changeToSlide(slideIndex)
@param slideIndex
Type: Integer
- Zero-based index of slide to change to. If the carousel is infinite, this number will be the index of the
<li>
in the original list PLUS the value of options>visibleItems (to accomodate for the cloned items added to the beginning/end to simulate an infinite loop).
Call this method to change the carousel to a specific slide, such as when deep-linking to a slide.
####getVirtualSlideIndex(slideIndex)
@param slideIndex
Type: Integer
- Zero-based index of a slide to find the 'virtual' index of
@return virtualIndex
Type: Integer
Utility method to get the perceived index of the slide. Because of the shifts in index values created by the infinite option, this method is a way to get the 'virtual' index of the slide, meaning the index of the original list item in the list of slides used to create the carousel. In a non-infinite carousel, the value return will be identical to the referenced index.
####getActiveSlideIndex()
@return slideIndex
Type Integer
Get the index of the current active slide. If the carousel is infinite, this number will be the index of the <li>
in the original list PLUS the value of options>visibleItems (to accomodate for the cloned items added to the beginning/end to simulate an infinite loop).
####startAutoRotation()
Manually start auto rotation for the slides (only allowed if options>infinite is set to true). If options>auto was set to true, the carousel will automatically rotate on instantiation. Use this method to manually start the auto rotation, such as after auto rotation was cancelled by some other event.
####stopAutoRotation() Manually stop carousel from auto-rotating.
##Known Issues
####HTML5 Video
- An existing bug in webkit: If the same video file is requested twice on the same page, the request gets blocked and the video won't load. Because of the duplicate slides created for infinite functionality, if the slides have a video, this can cause duplicate requests and the video won't load. You can manually remove the video tag from the duplicate slide to work around this issue.
- In mobile Safari, if a node containing a video is moved in the dom, the video will lose its controls. The carousel adds a wrapping div to all the slides during setup, which triggers this issue if there are videos.