Author: Jan Sorgalla
Version: 0.2.8 (Changelog)
Download: jcarousel.tar.gz or jcarousel.zip
Source Code: http://github.com/jsor/jcarousel
Bugtracker: http://github.com/jsor/jcarousel/issues
Licence: Dual licensed under the MIT
and GPL licenses.
jCarousel is a jQuery plugin for controlling a list of items in horizontal or vertical order. The items, which can be static HTML content or loaded with (or without) AJAX, can be scrolled back and forth (with or without animation).
The following examples illustrate the possibilities of jCarousel:
To use the jCarousel component, include the jQuery
library, the jCarousel source file and a jCarousel skin stylesheet file inside the <head>
tag
of your HTML document:
<script type="text/javascript" src="/path/to/jquery-1.4.2.min.js"></script> <script type="text/javascript" src="/path/to/lib/jquery.jcarousel.min.js"></script> <link rel="stylesheet" type="text/css" href="/path/to/skin/skin.css" />
The download package contains some example skin packages. Feel free to build your own skins based on it.
jCarousel expects a very basic HTML markup structure inside your HTML document:
<ul id="mycarousel" class="jcarousel-skin-name"> <!-- The content goes in here --> </ul>
jCarousel automatically wraps the required HTML markup around the list. The class attribute applies the jCarousel skin "name" to the carousel.
To setup jCarousel, add the following code inside the <head>
tag of your HTML document:
<script type="text/javascript"> jQuery(document).ready(function() { jQuery('#mycarousel').jcarousel({ // Configuration goes here }); }); </script>
jCarousel accepts a lot of configuration options, see chapter "Configuration" for further informations.
After jCarousel has been initialised, the fully created markup in the DOM is:
<div class="jcarousel-skin-name"> <div class="jcarousel-container"> <div class="jcarousel-clip"> <ul class="jcarousel-list"> <li class="jcarousel-item-1">First item</li> <li class="jcarousel-item-2">Second item</li> </ul> </div> <div disabled="disabled" class="jcarousel-prev jcarousel-prev-disabled"></div> <div class="jcarousel-next"></div> </div> </div>
As you can see, there are some elements added which have assigned classes (in addition to the classes you may have already assigned manually). Feel free to design your carousel with the classes you can see above.
<ul>
to the top <div>
element.<div>
's under <div class="jcarousel-container">
are the next/prev buttons of the carousel. The first one illustrates a disabled button, the second an enabled one. The disabled
button has the attribute
disabled
(which actually makes no sense for <div>
elements, but you can also use <button>
elements or
whatever you want) as well as the additional class jcarousel-prev-disabled
(or jcarousel-next-disabled
).<li>
elements of the list have the class
jcarousel-item-n
assigned where n
represents the position in the list.<ul class="jcarousel-list
jcarousel-list-horizontal">
for a horizontal carousel.By passing the callback function itemLoadCallback
as configuration
option, you are able to dynamically create <li>
items for the content.
<script type="text/javascript"> jQuery(document).ready(function() { jQuery('#mycarousel').jcarousel({ itemLoadCallback: itemLoadCallbackFunction }); }); </script>
itemLoadCallbackFunction
is a JavaScript function that is called
when the carousel requests a set of items to be loaded. Two parameters are
passed: The instance of the requesting carousel and a flag which indicates
the current state of the carousel ('init', 'prev' or 'next').
<script type="text/javascript"> function itemLoadCallbackFunction(carousel, state) { for (var i = carousel.first; i <= carousel.last; i++) { // Check if the item already exists if (!carousel.has(i)) { // Add the item carousel.add(i, "I'm item #" + i); } } }; </script>
jCarousel contains a convenience method add()
that can be
passed the index of the item to create and the innerHTML string of the
item to be
created. If the item already exists, it just updates the innerHTML. You can
access the index of the first and last visible element by the public variables carousel.first
and carousel.last
.
The instance of the carousel will be stored with the data()
method of jQuery under the key jcarousel
for a simple access.
If you have created a carousel like:
jQuery(document).ready(function() { jQuery('#mycarousel').jcarousel(); });
You can access the instance with:
var carousel = jQuery('#mycarousel').data('jcarousel');
You can also access methods of the instance directly, for example the add()
method:
var index = 1; var html = 'My content of item no. 1'; jQuery('#mycarousel').jcarousel('add', index, html);
Sometimes people are confused how to define the number of visible items because there is no option for this as they expect (Yes, there is an option visible
, we discuss this later).
You simply define the number of visible items by defining the width (or height) with the class .jcarousel-clip
(or the more distinct .jcarousel-clip-horizontal
and .jcarousel-clip-vertical
classes) in your skin stylesheet.
This offers a lot of flexibility, because you can define the width in pixel for a fixed carousel or in percent for a flexible carousel (This example shows a carousel with a clip width in percent, resize the browser to see it in effect).
So, why there is an option visible
? If you set the option visible
, jCarousel sets the width of the visible items to always make this number of items visible. Open this example and resize your browser window to see it in effect.
jCarousel accepts a list of options to control the appearance and behaviour of the carousel. Here is the list of options you may set:
Property | Type | Default | Description |
---|---|---|---|
vertical | bool | false | Specifies wether the carousel appears in horizontal or vertical orientation. Changes the carousel from a left/right style to a up/down style carousel. |
rtl | bool | false | Specifies wether the carousel appears in RTL (Right-To-Left) mode. |
start | integer | 1 | The index of the item to start with. |
offset | integer | 1 | The index of the first available item at initialisation. |
size | integer | Number of existing <li> elements if size is not passed explicitly | The number of total items. |
scroll | integer | 3 | The number of items to scroll by. |
visible | integer | null | If passed, the width/height of the items will be calculated and set depending on the width/height of the clipping, so that exactly that number of items will be visible. |
animation | mixed | "fast" | The speed of the scroll animation as string in jQuery terms ("slow"
or "fast" ) or milliseconds as integer
(See jQuery Documentation).
If set to 0, animation is turned off. |
easing | string | null | The name of the easing effect that you want to use (See jQuery Documentation). |
auto | integer | 0 | Specifies how many seconds to periodically autoscroll the content.
If set to 0 (default) then autoscrolling is turned off.
|
wrap | string | null | Specifies whether to wrap at the first/last item (or both) and jump
back to the start/end. Options are "first" , "last" ,
"both" or "circular" as string. If set to null ,
wrapping is turned off (default). |
initCallback | function | null | JavaScript function that is called right after initialisation of the carousel. Two parameters are passed: The instance of the requesting carousel and the state of the carousel initialisation (init, reset or reload). |
setupCallback | function | null | JavaScript function that is called right after the carousel is completely setup. One parameter is passed: The instance of the requesting carousel. |
itemLoadCallback | function | null | JavaScript function that is called when the carousel requests a set
of items to be loaded. Two parameters are passed: The instance of the
requesting carousel and the state of the carousel action (prev, next
or init). Alternatively, you can pass a hash of one or two functions
which are triggered before and/or after animation:
itemLoadCallback: { onBeforeAnimation: callback1, onAfterAnimation: callback2 } |
itemFirstInCallback | function | null | JavaScript function that is called (after the scroll animation) when
an item becomes the first one in the visible range of the carousel.
Four parameters are passed: The instance of the requesting carousel
and the <li> object itself, the index which indicates
the position of the item in the list and the state of the carousel action
(prev, next or init). Alternatively, you can pass a hash of one or two
functions which are triggered before and/or after animation:
itemFirstInCallback: { onBeforeAnimation: callback1, onAfterAnimation: callback2 } |
itemFirstOutCallback | function | null | JavaScript function that is called (after the scroll animation) when
an item isn't longer the first one in the visible range of the carousel.
Four parameters are passed: The instance of the requesting carousel
and the <li> object itself, the index which indicates
the position of the item in the list and the state of the carousel action
(prev, next or init). Alternatively, you can pass a hash of one or two
functions which are triggered before and/or after animation:
itemFirstOutCallback: { onBeforeAnimation: callback1, onAfterAnimation: callback2 } |
itemLastInCallback | function | null | JavaScript function that is called (after the scroll animation) when
an item becomes the last one in the visible range of the carousel. Four
parameters are passed: The instance of the requesting carousel and the
<li> object itself, the index which indicates the
position of the item in the list and the state of the carousel action
(prev, next or init). Alternatively, you can pass a hash of one or two
functions which are triggered before and/or after animation:
itemLastInCallback: { onBeforeAnimation: callback1, onAfterAnimation: callback2 } |
itemLastOutCallback | function | null | JavaScript function that is called when an item isn't longer the last
one in the visible range of the carousel. Four parameters are passed:
The instance of the requesting carousel and the <li>
object itself, the index which indicates the position of the item in
the list and the state of the carousel action (prev, next or init).
Alternatively, you can pass a hash of one or two functions which are
triggered before and/or after animation:
itemLastOutCallback: { onBeforeAnimation: callback1, onAfterAnimation: callback2 } |
itemVisibleInCallback | function | null | JavaScript function that is called (after the scroll animation) when
an item is in the visible range of the carousel. Four parameters are
passed: The instance of the requesting carousel and the <li>
object itself, the index which indicates the position of the item in
the list and the state of the carousel action (prev, next or init).
Alternatively, you can pass a hash of one or two functions which are
triggered before and/or after animation:
itemVisibleInCallback: { onBeforeAnimation: callback1, onAfterAnimation: callback2 } |
itemVisibleOutCallback | function | null | JavaScript function that is called (after the scroll animation) when
an item isn't longer in the visible range of the carousel. Four parameters
are passed: The instance of the requesting carousel and the <li>
object itself, the index which indicates the position of the item in
the list and the state of the carousel action (prev, next or init).
Alternatively, you can pass a hash of one or two functions which are
triggered before and/or after animation:
itemVisibleOutCallback: { onBeforeAnimation: callback1, onAfterAnimation: callback2 } |
animationStepCallback | function | null | JavaScript function that is called after each animation step. This
function is directly passed to jQuery's .animate() method
as the step parameter. See the jQuery documentation for the
parameters it will receive. |
buttonNextCallback | function | null | JavaScript function that is called when the state of the 'next' control is changing. The responsibility of this method is to enable or disable the 'next' control. Three parameters are passed: The instance of the requesting carousel, the control element and a flag indicating whether the button should be enabled or disabled. |
buttonPrevCallback | function | null | JavaScript function that is called when the state of the 'previous' control is changing. The responsibility of this method is to enable or disable the 'previous' control. Three parameters are passed: The instance of the requesting carousel, the control element and a flag indicating whether the button should be enabled or disabled. |
buttonNextHTML | string | <div></div> |
The HTML markup for the auto-generated next button. If set to null ,
no next-button is created. |
buttonPrevHTML | string | <div></div> |
The HTML markup for the auto-generated prev button. If set to null ,
no prev-button is created. |
buttonNextEvent | string | "click" | Specifies the event which triggers the next scroll. |
buttonPrevEvent | string | "click" | Specifies the event which triggers the prev scroll. |
itemFallbackDimension | integer | null | If, for some reason, jCarousel can not detect the width of an item, you can set a fallback dimension (width or height, depending on the orientation) here to ensure correct calculations. |
Thanks to John Resig for his fantastic jQuery
library.
jCarousel is inspired by the Carousel
Component written by Bill Scott.