jCarousel Documentation

Release 0.3.0-beta

Jan Sorgalla

October 17, 2013

CONTENTS

Reference 1.1 Installation . 1.2 Conguration 1.3 API . . . . . 1.4 Usage . . . . 1.5 Events . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

3 3 4 7 9 12 17 17 29 29 31 33

Plugins 2.1 Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Cookbook 3.1 How to dene a custom start position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Credits License

4 5

ii

jCarousel Documentation, Release 0.3.0-beta

jCarousel is a jQuery plugin for controlling a list of items in horizontal or vertical order. It provides a full-featured and exible toolset for navigating any HTML based content in a carousel-like fashion. Download | Repository at GitHub | Bugtracker

CONTENTS

jCarousel Documentation, Release 0.3.0-beta

CONTENTS

CHAPTER

ONE

REFERENCE
1.1 Installation
To use the jCarousel component, include the jQuery library and the jCarousel source le into your HTML document:
<script type="text/javascript" src="//ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"> </script> <script type="text/javascript" src="/path/to/jquery.jcarousel.js"> </script>

jCarousel expects a very basic HTML markup structure inside your HTML document:
<div class="jcarousel"> <ul> <li>...</li> <li>...</li> </ul> </div>

Note: The documentation refers to the elements as root element, list element and item element(s):
<div class="jcarousel"> <--------------------------------| Root element <ul> <-------------------------------| List element | <li>...</li> <---| Item element | | <li>...</li> <---| Item element | | </ul> <------------------------------| | </div> <-------------------------------------------------|

This structure is only an example and not required. You could also use a structure like:
<div class="mycarousel"> <-------------------------------| Root element <div> <------------------------------| List element | <p>...</p> <-----| Item element | | <p>...</p> <-----| Item element | | </div> <-----------------------------| | </div> <-------------------------------------------------|

The only requirement is, that it consists of a root element, list element and item elements.

jCarousel Documentation, Release 0.3.0-beta

1.1.1 Setup
To setup jCarousel, add the following code to your HTML document:
<script type="text/javascript"> $(function() { $(.jcarousel).jcarousel({ // Configuration goes here }); }); </script>

See Conguration for all available conguration options. These are the minimal CSS settings for a horizontal carousel:
.jcarousel { position: relative; overflow: hidden; /* You need at least a height, adjust this to your needs */ height: 100px; } .jcarousel ul { width: 20000em; position: absolute; list-style: none; margin: 0; padding: 0; } .jcarousel li { float: left; }

1.2 Conguration
jCarousel accepts the following options: See Also: Setup Set conguration options on initialization. reload method Set conguration options at runtime. list A function or a jQuery selector to select the list inside the root element. A function will be called in the context of the carousel instance. Example:
$(.jcarousel).jcarousel({ list: .jcarousel-list });

Default:
function() { return this.element().children().eq(0); }

Chapter 1. Reference

jCarousel Documentation, Release 0.3.0-beta

items A function or a jQuery selector to select the items inside the list element. A function will be called in the context of the carousel instance. Example:
$(.jcarousel).jcarousel({ items: .jcarousel-item });

Default:
function() { return this.list().children(); }

animation The speed of the scroll animation as string in jQuery terms ("slow" or "fast") or milliseconds as integer (See the documentation for jQuery animate). Alternatively, this can be a map of options like the one jQuery.animate accepts as second argument. Example:
$(.jcarousel).jcarousel({ animation: slow }); $(.jcarousel).jcarousel({ animation: { duration: 800, easing: linear, complete: function() { } } });

Default: 400 transitions If set to true, CSS3 transitions are used for animations. Alternatively, this can be a map of the following options: transforms: If set to true, 2D transforms are used for better hardware acceleration. transforms3d: If set to true, 3D transforms are used for full hardware acceleration. easing: Value will be used as the transition-timing-function (e.g. ease or linear). Warning: jCarousel does not check if the users browser supports transitions and/or transforms. You have to do that yourself when setting the option. You can for example use Modernizr for browser feature detection. If youre not including it already in your site, you can use this minimal build. Example:
$(.jcarousel).jcarousel({ transitions: true }); $(.jcarousel).jcarousel({ transitions: Modernizr.csstransitions ? { transforms: Modernizr.csstransforms,

1.2. Conguration

jCarousel Documentation, Release 0.3.0-beta

transforms3d: Modernizr.csstransforms3d, easing: ease } : false });

Default: false wrap Species whether to wrap at the rst or 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). Example:
$(.jcarousel).jcarousel({ wrap: both });

Default: null vertical Species whether the carousel appears in vertical orientation. Changes the carousel from a left/right style to a up/down style carousel. If set to null, jCarousel tries to auto-detect the orientation by simply checking if the lists height is greater than the lists width. Example:
$(.jcarousel).jcarousel({ vertical: true });

Default: null rtl Species wether the carousel appears in RTL (Right-To-Left) mode. If set to null, jCarousel looks for dir="rtl" attribute on the root element (or to any of its parent elements) and if found, automatically sets rtl to true. Example:
$(.jcarousel).jcarousel({ rtl: true });

Example with dir attribute:

<div class="jcarousel" dir="rtl"> <ul> <li>...</li> </ul> </div> <script> $(.jcarousel).jcarousel(); </script>

Default: null center Species wether the targeted item should be centered inside the root element. Warning: This feature is experimental and may not work with all setups.

Chapter 1. Reference

jCarousel Documentation, Release 0.3.0-beta

Example:
$(.jcarousel).jcarousel({ center: true });

Default: false

1.3 API
See Also: Calling methods on the jCarousel instance Call methods on the jCarousel instance.

1.3.1 Carousel-related methods

.jcarousel(scroll, target [, animate [, callback]]) Scrolls to a specic item or relative by a given offset (See section Available formats for the target argument for more information about the target argument). If the argument animate is given and false, it just jumps to the position without animation. If the argument callback is given and a valid function, it is called after the animation is nished. The function receives as rst argument a boolean indicating if a scrolling actually happend. It can be false for the following reasons: The carousel is already animating The target argument is invalid The carousel is already on the requested position An event has cancelled the scrolling Example:
$(.jcarousel).jcarousel(scroll, +=1, true, function(scrolled) { if (scrolled) { console.log(The carousel has been scrolled); } else { console.log(The carousel has not been scrolled); } });

.jcarousel(reload [, options]) Reloads the carousel. This method is useful to reinitialize the carousel if you have changed the content of the list from the outside or want to change options that affect appearance of the carousel at runtime. Example:
$(.jcarousel).jcarousel(reload, { animation: slow });

.jcarousel(destroy) Removes the jCarousel functionality completely. This will return the element back to its initial state. Example:

1.3. API

jCarousel Documentation, Release 0.3.0-beta

$(.jcarousel).jcarousel(destroy);

.jcarousel(list) Returns the list element as jQuery object. Example:

var list = $(.jcarousel).jcarousel(list);

1.3.2 Item-related methods

Note: Please note that the item-related methods return different results depending on the state of the carousel. That means for example, that after each scroll, these methods return a different set of items. The following example illustrates how to use these methods inside event callbacks:
$(.jcarousel) .on(animateend.jcarousel, function(event, carousel) { var currentFirstItem = carousel.jcarousel(first); var currentLastItem = carousel.jcarousel(last); });

.jcarousel(items) Returns all items as jQuery object. Example:

var items = $(.jcarousel).jcarousel(items);

.jcarousel(target) Returns the targeted item as jQuery object. Example:

var target = $(.jcarousel).jcarousel(target);

.jcarousel(first) Returns the rst visible item as jQuery object. Example:

var first = $(.jcarousel).jcarousel(first);

.jcarousel(last) Returns the last visible item as jQuery object. Example:

var last = $(.jcarousel).jcarousel(last);

.jcarousel(visible) Returns all visible items as jQuery object. Example:

var visible = $(.jcarousel).jcarousel(visible);

.jcarousel(fullyvisible) Returns all fully visible items as jQuery object. Example:

var fullyvisible = $(.jcarousel).jcarousel(fullyvisible);

Chapter 1. Reference

jCarousel Documentation, Release 0.3.0-beta

1.4 Usage
1.4.1 Calling methods on the jCarousel instance
If you have created a carousel like:
$(function() { $(.jcarousel).jcarousel(); });

You can later call methods on the jCarousel instance like:

$(.jcarousel).jcarousel(scroll, +=2);

The rst argument is the method name. The following arguments are the arguments for the called method. See API for available methods.

1.4.2 Navigating the carousel

Note: A more comfortable way is to use a navigation plugin: Control Plugin Pagination Plugin jCarousel offers no built in controls to navigate through the carousel. But you can simply implement navigation controls using the scroll method.
$(.jcarousel).jcarousel(scroll, target);

Available formats for the target argument index Scrolls to the item at the given index (Note that indexes are 0-based). Example:
$(.jcarousel).jcarousel(scroll, 0);

-index Scrolls to the item at the given index counting backwards from the end of the list. Example:
$(.jcarousel).jcarousel(scroll, -1);

object Scrolls to the given object. Example:

$(.jcarousel).jcarousel(scroll, $(.jcarousel li:eq(2)));

+=offset Scrolls the carousel forward by the given offset relatively from the current position. Example:
$(.jcarousel).jcarousel(scroll, +=1);

1.4. Usage

jCarousel Documentation, Release 0.3.0-beta

-=offset Scrolls the carousel backwards by the given offset relatively from the current position. Example:
$(.jcarousel).jcarousel(scroll, -=1);

A simple example for previous and next controls:

$(.jcarousel-prev).click(function() { $(.jcarousel).jcarousel(scroll, -=1); }); $(.jcarousel-next).click(function() { $(.jcarousel).jcarousel(scroll, +=1); });

1.4.3 Dening the number of visible items

You simply dene the number of visible items by dening the width (or height for a vertical carousel) of the root element (if you use the default from this document, you do that with the class .jcarousel in your stylesheet). This offers a lot of exibility, because you can dene the width in pixel for a xed carousel or in percent for a exible carousel. Fixed carousel, always 3 visible items:
.jcarousel { position: relative; overflow: hidden; width: 300px; } .jcarousel li { float: left; width: 100px; }

Flexible carousel, the number of visible items depend on the width of the roots parent element:
.jcarousel { position: relative; overflow: hidden; width: 100%; } .jcarousel li { float: left; width: 100px; }

1.4.4 Vertical carousels

jCarousel tries to auto-detect the orientation by simply checking if the list elementss height is greater than the list elements width. If auto-detection doesnt work, you can explicitly pass the vertical option:

10

Chapter 1. Reference

jCarousel Documentation, Release 0.3.0-beta

$(.jcarousel).jcarousel({ vertical: true });

1.4.5 RTL (Right-To-Left) carousels

jCarousel tries to auto-detect if the carousel should run in RTL mode by looking for a dir attribute with the value rtl on the root or any of its parent elements.
<div class="jcarousel" dir="rtl"> <ul> <!-- The content goes in here --> </ul> </div>

If auto-detection doesnt work, you can explicitly pass the rtl option (the dir="rtl" attribute is still required):
$(.jcarousel).jcarousel({ rtl: true });

Note: When running a carousel in RTL mode, you should ensure to oat the items to the right:
.jcarousel[dir=rtl] li { float: right; }

1.4.6 Manipulating the carousel

If you manipulate the carousel from the outside (eg. adding or removing items from the list), ensure that you call .jcarousel(reload) afterwards so that jCarousel becomes aware of the changes:
$(function() { $(.jcarousel).jcarousel({ // Configuration goes here }); // Append items $(.jcarousel ul) .append(<li>Item 1</li>) .append(<li>Item 2</li>); // Reload carousel $(.jcarousel).jcarousel(reload); });

Existing items should only be manipulated, not completely replaced:

$(function() { // Dont do that $(.jcarousel li:eq(0)) .replaceWith(<li class="myclass">Item 1</li>); // Do this

1.4. Usage

11

jCarousel Documentation, Release 0.3.0-beta

$(.jcarousel li:eq(0)) .addClass(myclass) .text(Item 1); });

If you are removing items, make sure they are currently not visible:
$(function() { var carousel = $(.jcarousel), item = carousel.find(li:eq(0)); if (carousel.jcarousel(visible).index(item) < 0) { item.remove(); carousel.jcarousel(reload); } });

1.5 Events
After initialization, jCarousel triggers the following events on the root and the items elements of the carousel: Note: Some events like create.jcarousel are triggered from the constructor, so you have to bind the events before you initialize the carousel:
$(.jcarousel) // Bind first .on(create.jcarousel, function(event, carousel) { // Do something }) // Initialize at last step .jcarousel();

1.5.1 Root element events

create.jcarousel Triggered on creation of the carousel. Example:
$(.jcarousel).on(create.jcarousel, function(event, carousel) { // "this" refers to the root element // "carousel" is the jCarousel instance });

createend.jcarousel Triggered after creation of the carousel. Example:

$(.jcarousel).on(createend.jcarousel, function(event, carousel) { // "this" refers to the root element // "carousel" is the jCarousel instance });

12

Chapter 1. Reference

jCarousel Documentation, Release 0.3.0-beta

reload.jcarousel Triggered when the reload method is called. Example:

$(.jcarousel).on(reload.jcarousel, function(event, carousel) { // "this" refers to the root element // "carousel" is the jCarousel instance });

reloadend.jcarousel Triggered after the reload method is called. Example:

$(.jcarousel).on(reloadend.jcarousel, function(event, carousel) { // "this" refers to the root element // "carousel" is the jCarousel instance });

destroy.jcarousel Triggered when the destroy method is called. Example:

$(.jcarousel).on(destroy.jcarousel, function(event, carousel) { // "this" refers to the root element // "carousel" is the jCarousel instance });

destroyend.jcarousel Triggered after the destroy method is called. Example:

$(.jcarousel).on(destroyend.jcarousel, function(event, carousel) { // "this" refers to the root element // "carousel" is the jCarousel instance });

scroll.jcarousel Triggered when the scroll method is called. Example:

$(.jcarousel).on(scroll.jcarousel, function(event, carousel, target, animate) { // "this" refers to the root element // "carousel" is the jCarousel instance // "target" is the target argument passed to the scroll method // "animate" is the animate argument passed to the scroll method // indicating whether jCarousel was requested to do an animation });

scrollend.jcarousel Triggered after the scroll method is called. Note: This method is triggered at the end of the scroll method and not when the animation is nished. Example:
$(.jcarousel).on(scrollend.jcarousel, function(event, carousel) { // "this" refers to the root element // "carousel" is the jCarousel instance });

animate.jcarousel Triggered when the carousel starts a animation. Example:

1.5. Events

13

jCarousel Documentation, Release 0.3.0-beta

$(.jcarousel).on(animate.jcarousel, function(event, carousel) { // "this" refers to the root element // "carousel" is the jCarousel instance });

animateend.jcarousel Triggered after the carousel has nished a animation. Example:

$(.jcarousel).on(animateend.jcarousel, function(event, carousel) { // "this" refers to the root element // "carousel" is the jCarousel instance });

1.5.2 Item element events

itemtargetin.jcarousel Triggered when the item becomes the targeted item. Example:
$(.jcarousel).on(itemtargetin.jcarousel, li, function(event, carousel) { // "this" refers to the item element // "carousel" is the jCarousel instance });

itemtargetout.jcarousel Triggered when the item is no longer the targeted item. Example:
$(.jcarousel).on(itemtargetout.jcarousel, li, function(event, carousel) { // "this" refers to the item element // "carousel" is the jCarousel instance });

itemfirstin.jcarousel Triggered when the item becomes the rst visible item. Example:
$(.jcarousel).on(itemfirstin.jcarousel, li, function(event, carousel) { // "this" refers to the item element // "carousel" is the jCarousel instance });

itemfirstout.jcarousel Triggered when the item is no longer the rst visible item. Example:
$(.jcarousel).on(itemfirstout.jcarousel, li, function(event, carousel) { // "this" refers to the item element // "carousel" is the jCarousel instance });

itemlastin.jcarousel Triggered when the item becomes the last visible item. Example:
$(.jcarousel).on(itemlastin.jcarousel, li, function(event, carousel) { // "this" refers to the item element // "carousel" is the jCarousel instance });

14

Chapter 1. Reference

jCarousel Documentation, Release 0.3.0-beta

itemlastout.jcarousel Triggered when the item is no longer the last visible item. Example:
$(.jcarousel).on(itemlastout.jcarousel, li, function(event, carousel) { // "this" refers to the item element // "carousel" is the jCarousel instance });

itemvisiblein.jcarousel Triggered when the item becomes a visible item. Example:

$(.jcarousel).on(itemvisiblein.jcarousel, li, function(event, carousel) { // "this" refers to the item element // "carousel" is the jCarousel instance });

itemvisibleout.jcarousel Triggered when the item is no longer a visible item. Example:

$(.jcarousel).on(itemvisibleout.jcarousel, li, function(event, carousel) { // "this" refers to the item element // "carousel" is the jCarousel instance });

itemfullyvisiblein.jcarousel Triggered when the item becomes a fully visible item. Example:
$(.jcarousel).on(itemfullyvisiblein.jcarousel, li, function(event, carousel) { // "this" refers to the item element // "carousel" is the jCarousel instance });

itemfullyvisibleout.jcarousel Triggered when the item is no longer a fully visible item. Example:
$(.jcarousel).on(itemfullyvisibleout.jcarousel, li, function(event, carousel) { // "this" refers to the item element // "carousel" is the jCarousel instance });

1.5. Events

15

jCarousel Documentation, Release 0.3.0-beta

16

Chapter 1. Reference

CHAPTER

TWO

PLUGINS
2.1 Plugins
By default, the jCarousel core only contains the minimum functionality needed to built carousel widgets. Specialized features are provided through plugins. jCarousel comes with the following plugins:

2.1.1 Control Plugin

The jCarousel Control Plugin provides controls for jCarousel. Reference
Installation

A control is basically a HTML element (<a>, <button> etc.) which scrolls the carousel when clicking on it. A simple basic HTML markup structure would be:
<!-- Wrapper --> <div> <!-- Carousel --> <div class="jcarousel"> <ul> <li>...</li> <li>...</li> </ul> </div> <!-- Controls --> <a class="jcarousel-prev" href="#">Prev</a> <a class="jcarousel-next" href="#">Next</a> </div>

To setup the plugin, add the following code to your HTML document:
<script type="text/javascript"> $(function() { $(.jcarousel).jcarousel({ // Core configuration goes here

17

jCarousel Documentation, Release 0.3.0-beta

}); $(.jcarousel-prev).jcarouselControl({ target: -=1 }); $(.jcarousel-next).jcarouselControl({ target: +=1 }); }); </script>

See section Available formats for the target argument for more information about the target argument As you can see, you setup the controls independently from the carousel and the plugin tries to autodetect the carousel. This works best if you enclose the carousel and its controls inside a mutual wrapper element. If that fails or isnt possible, you can pass the related carousel instance as an option:
<script type="text/javascript"> var carousel = $(.jcarousel).jcarousel({ // Core configuration goes here }); $(.jcarousel-prev).jcarouselControl({ target: -=1, carousel: carousel }); </script>

Conguration

The plugin accepts the following options: target The target for the control. Accepts the same argument as the scroll() method. Example:
$(.jcarousel-control).jcarouselControl({ target: +=3 });

Default: +=1 event The event which triggers the control. Example:
$(.jcarousel-control).jcarouselControl({ event: mouseover });

Default: click method The method to call on the carousel. Plugins may provide alternate methods for scrolling the carousel, e.g. ScrollIntoView Plugin. scrollIntoView from the

Alternatively, method can be a function which will be called in the context of the plugin instance.

18

Chapter 2. Plugins

jCarousel Documentation, Release 0.3.0-beta

Example:
$(.jcarousel-control).jcarouselControl({ method: scrollIntoView }); $(.jcarousel-control).jcarouselControl({ method: function() { this.carousel() .jcarousel(myScrollingMethod, this.options(target)); } });

Default: scroll carousel The corresponding carousel as jQuery object. This is optional. By default, the plugin tries to autodetect the carousel. Example:
$(.jcarousel-control).jcarouselControl({ carousel: $(.jcarousel) });

Default: null
API

The plugin exposes the following methods: .jcarouselControl(reload [, options]) Reloads the plugin. This method is useful to reinitialize the plugin or if you want to change options at runtime. Example:
$(.jcarousel-control).jcarouselControl(reload, { interval: 1500 });

.jcarouselControl(destroy) Removes the control functionality completely. This will return the element back to its initial state. Example:
$(.jcarousel-control).jcarouselControl(destroy);

Events

After initialization, the plugin triggers the following events on the element: Note: This is how the plugin understands active and inactive states: If the target option is relative, +=1 for example, the control is active if there is at least on more item to scroll, inactive otherwise (if youre at the last item in this case). If the target option is absolute, 0 for example (always scrolls to the rst item), the control is active if the targeted item is at position 0, inactive otherwise.

2.1. Plugins

19

jCarousel Documentation, Release 0.3.0-beta

active.jcarouselcontrol Triggered when the control becomes active. Example:

$(.jcarousel-control).on(active.jcarouselcontrol, function() { // Do something });

inactive.jcarouselcontrol Triggered when the control becomes inactive. Example:

$(.jcarousel-control).on(inactive.jcarouselcontrol, function() { // Do something });

create.jcarouselcontrol Triggered on creation of the plugin. Example:

$(.jcarousel-control).on(create.jcarouselcontrol, function() { // Do something });

createend.jcarouselcontrol Triggered after creation of the plugin. Example:

$(.jcarousel-control).on(createend.jcarouselcontrol, function() { // Do something });

reload.jcarouselcontrol Triggered when the reload method is called. Example:

$(.jcarousel-control).on(reload.jcarouselcontrol, function() { // Do something });

reloadend.jcarouselcontrol Triggered after the reload method is called. Example:

$(.jcarousel-control).on(reloadend.jcarouselcontrol, function() { // "this" refers to the element });

destroy.jcarouselcontrol Triggered when the destroy method is called. Example:

$(.jcarousel-control).on(destroy.jcarouselcontrol, function() { // Do something });

destroyend.jcarouselcontrol Triggered after the destroy method is called. Example:

$(.jcarousel-control).on(destroyend.jcarouselcontrol, function() { // Do something });

20

Chapter 2. Plugins

jCarousel Documentation, Release 0.3.0-beta

2.1.2 Pagination Plugin

The jCarousel Pagination Plugin provides a pagination for jCarousel. Reference
Installation

The plugin provides a pagination widget for carousels. A simple basic HTML markup structure would be:
<!-- Wrapper --> <div> <!-- Carousel --> <div class="jcarousel"> <ul> <li>...</li> <li>...</li> </ul> </div> <!-- Pagination --> <div class="jcarousel-pagination"> <!-- Pagination items will be generated in here --> </div> </div>

To setup the plugin, add the following code to your HTML document:
<script type="text/javascript"> $(function() { $(.jcarousel).jcarousel({ // Core configuration goes here }); $(.jcarousel-pagination).jcarouselPagination({ // Configuration options }); }); </script>

As you can see, you setup the pagination independently from the carousel and the plugin tries to autodetect the carousel. This works best if you enclose the carousel and its pagination inside a mutual wrapper element. If that fails or isnt possible, you can pass the related carousel instance as an option:
<script type="text/javascript"> var carousel = $(.jcarousel).jcarousel({ // Core configuration goes here }); $(.jcarousel-pagination).jcarouselPagination({ carousel: carousel }); </script>

2.1. Plugins

21

jCarousel Documentation, Release 0.3.0-beta

Conguration

The plugin accepts the following options: perPage The number of carousel items per page or a function returning the number. If perPage is not set or null, the plugin calculates the pages depending on the number of visible carousel items. Example:
$(.jcarousel-pagination).jcarouselPagination({ perPage: 3 });

Default: null item A function returning the markup for a page item of the pagination either as string or jQuery object. The function will be called in the context of the plugin instance and receives two arguments: 1. The page number. 2. A jQuery object containing the carousel items visible on this page. Example:
$(.jcarousel-pagination).jcarouselPagination({ item: function(page, carouselItems) { return <li><a href="# + page + ">Page + page + </a></li>; } });

Default:
function(page, carouselItems) { return <a href="# + page + "> + page + </a>; }

carousel The corresponding carousel as jQuery object. This is optional. By default, the plugin tries to autodetect the carousel. Example:
$(.jcarousel-pagination).jcarouselPagination({ carousel: $(.jcarousel) });

Default: null
API

The plugin exposes the following methods: .jcarouselPagination(reload [, options]) Reloads the plugin. This method is useful to reinitialize the plugin or if you want to change options at runtime. Example:
$(.jcarousel-pagination).jcarouselPagination(reload, { interval: 1500 });

22

Chapter 2. Plugins

jCarousel Documentation, Release 0.3.0-beta

.jcarouselPagination(destroy) Removes the pagination functionality completely. This will return the element back to its initial state. Example:
$(.jcarousel-pagination).jcarouselPagination(destroy);

Events

After initialization, the plugin triggers the following events on the root and the item elements: Root element events create.jcarouselpagination Triggered on creation of the plugin. Example:
$(.jcarousel-pagination).on(create.jcarouselpagination, function() { // Do something });

createend.jcarouselpagination Triggered after creation of the plugin. Example:

$(.jcarousel-pagination).on(createend.jcarouselpagination, function() { // Do something });

reload.jcarouselpagination Triggered when the reload method is called. Example:

$(.jcarousel-pagination).on(reload.jcarouselpagination, function() { // Do something });

reloadend.jcarouselpagination Triggered after the reload method is called. Example:

$(.jcarousel-pagination).on(reloadend.jcarouselpagination, function() { // "this" refers to the element });

destroy.jcarouselpagination Triggered when the destroy method is called. Example:

$(.jcarousel-pagination).on(destroy.jcarouselpagination, function() { // Do something });

destroyend.jcarouselpagination Triggered after the destroy method is called. Example:

$(.jcarousel-pagination).on(destroyend.jcarouselpagination, function() { // Do something });

2.1. Plugins

23

jCarousel Documentation, Release 0.3.0-beta

Item element events active.jcarouselpagination Triggered when the item becomes active. Example:
$(.jcarousel-pagination).on(active.jcarouselpagination, a, function() { // Do something });

inactive.jcarouselpagination Triggered when the item becomes inactive. Example:

$(.jcarousel-pagination).on(inactive.jcarouselpagination, a, function() { // Do something });

You should use delegated events to attach event handler to the pagination items since they are created and removed on the y depending on your conguration. Example:
$(.jcarousel-pagination) .on(active.jcarouselpagination, a, function() { $(this).addClass(active); }) .on(inactive.jcarouselpagination, a, function() { $(this).removeClass(active); });

2.1.3 Autoscroll Plugin

The jCarousel Autoscroll Plugin provides autoscrolling support for jCarousel. Reference
Installation

The plugin provides autoscrolling support for carousels. To setup the plugin, add the following code to your HTML document:
<script type="text/javascript"> $(function() { $(.jcarousel) .jcarousel({ // Core configuration goes here }) .jcarouselAutoscroll({ // Plugin configuration goes here }); }); </script>

24

Chapter 2. Plugins

jCarousel Documentation, Release 0.3.0-beta

Conguration

The plugin accepts the following options: target The target for the autoscrolling. Accepts the same argument as the scroll() method. Example:
$(.jcarousel).jcarouselAutoscroll({ target: +=3 });

Default: +=1 interval The autoscrolling interval in milliseconds. Example:

$(.jcarousel).jcarouselAutoscroll({ interval: 1000 });

Default: 3000 autostart Whether to autostart autoscrolling. Example:

$(.jcarousel).jcarouselAutoscroll({ autostart: false });

Default: true
API

The plugin exposes the following methods: .jcarouselAutoscroll(start) Starts the autoscrolling. Example:
$(.jcarousel).jcarouselAutoscroll(start);

.jcarouselAutoscroll(stop) Stops the autoscrolling. Example:

$(.jcarousel).jcarouselAutoscroll(stop);

.jcarouselAutoscroll(reload [, options]) Reloads the plugin. This method is useful to reinitialize the plugin or if you want to change options at runtime. Example:
$(.jcarousel).jcarouselAutoscroll(reload, { interval: 1500 });

.jcarouselAutoscroll(destroy) Removes the autoscrolling functionality completely. This will return the element back to its initial state.

2.1. Plugins

25

jCarousel Documentation, Release 0.3.0-beta

Example:
$(.jcarousel).jcarouselAutoscroll(destroy);

Events

After initialization, the plugin triggers the following events on the element: create.jcarouselautoscroll Triggered on creation of the plugin. Example:
$(.jcarousel).on(create.jcarouselautoscroll, function() { // Do something });

createend.jcarouselautoscroll Triggered after creation of the plugin. Example:

$(.jcarousel).on(createend.jcarouselautoscroll, function() { // Do something });

reload.jcarouselautoscroll Triggered when the reload method is called. Example:

$(.jcarousel).on(reload.jcarouselautoscroll, function() { // Do something });

reloadend.jcarouselautoscroll Triggered after the reload method is called. Example:

$(.jcarousel).on(reloadend.jcarouselautoscroll, function() { // "this" refers to the element });

destroy.jcarouselautoscroll Triggered when the destroy method is called. Example:

$(.jcarousel).on(destroy.jcarouselautoscroll, function() { // Do something });

destroyend.jcarouselautoscroll Triggered after the destroy method is called. Example:

$(.jcarousel).on(destroyend.jcarouselautoscroll, function() { // Do something });

2.1.4 ScrollIntoView Plugin

The jCarousel ScrollIntoView Plugin extends the jCarousel core by a scrollIntoView method. Calling the method ensures that the passed target is fully visible inside the carousel. 26 Chapter 2. Plugins

jCarousel Documentation, Release 0.3.0-beta

API The plugin exposes the following method: .jcarousel(scrollIntoView, target [, animate [, callback]]) The arguments are similar to the scroll() method. If the targeted item is currently not fully visible, it will be the rst or last fully visible item after calling the method. Example:
$(.jcarousel).jcarousel(scrollIntoView, 2, true, function(scrolled) { if (scrolled) { console.log(The carousel has been scrolled); } else { console.log(The carousel has not been scrolled); } });

2.1. Plugins

27

jCarousel Documentation, Release 0.3.0-beta

28

Chapter 2. Plugins

CHAPTER

THREE

COOKBOOK
3.1 How to dene a custom start position
Sometimes, you dont want to start your carousel at the rst item but dene a custom start position. This can be achieved in two ways: Either by listening to the createend event or by dening the start position via CSS.

3.1.1 Setting the start position through an event

You can set the start position by listening to the createend event and calling the scroll method:
$(.jcarousel) .on(createend.jcarousel, function() { // Arguments: // 1. The method to call // 2. The index of the item (note that indexes are 0-based) // 3. A flag telling jCarousel jumping to the index without animation $(this).jcarousel(scroll, 2, false); }) .jcarousel();

3.1.2 Setting the start position through CSS

You can also set the initial position of the list through CSS and jCarousel will gure out which item to use as the start item:
.jcarousel ul { /* ...other styles left out... */ left: -150px; }

Assuming your items have a width of 75px, the start item will be the third item.

29

jCarousel Documentation, Release 0.3.0-beta

30

Chapter 3. Cookbook

CHAPTER

FOUR

CREDITS
jCarousel is written on top of jQuery and was originally inspired by the Carousel Component by Bill Scott.

31

jCarousel Documentation, Release 0.3.0-beta

32

Chapter 4. Credits

CHAPTER

FIVE

LICENSE
Copyright 2013 Jan Sorgalla. Released under the MIT license.

33