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).
Examples
The following examples illustrate the possibilities of jCarousel:
To use the jCarousel component, include the jQuery
library, the jCarousel source file, the jCarousel core stylesheet file and
a jCarousel skin stylesheet file inside the <head> tag
of your HTML document:
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.
Note:
The skin class "jcarousel-skin-name" has been moved
from the <ul> to the top <div> element.
The first nested <div> under <div class="jcarousel-container">
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).
All <li> elements of the list have the class jcarousel-item-n
assigned where n represents the position in the list.
Not shown here is, that all classes are followed by additional classes with a suffix
dependent on the orientation of the carousel, ie. <ul class="jcarousel-list
jcarousel-list-horizontal"> for a horizontal carousel.
Dynamic content loading
By passing the callback function itemLoadCallback as configuration
option, you are able to dynamically create <li> items for the content.
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.
Configuration
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.
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.
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"
or "both" as string. If set to null,
wrapping is turned off (default). You can also pass "circular"
as option to enable support for circular carousels. See the example
Circular carousel on how
to implement it.
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)
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:
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:
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:
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:
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:
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:
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:
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.
Compatibility
jCarousel has been tested and works on the following browsers: