j carousel

jCarousel DocumentationRelease 0.3.0-beta

Jan Sorgalla

October 17, 2013

CONTENTS

1 Reference 31.1 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.3 API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71.4 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91.5 Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

2 Plugins 172.1 Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

3 Cookbook 293.1 How to define a custom start position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

4 Credits 31

5 License 33

i

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 andflexible toolset for navigating any HTML based content in a carousel-like fashion.

Download | Repository at GitHub | Bugtracker

CONTENTS 1

https://github.com/jsor/jcarousel/archive/master.zip

https://github.com/jsor/jcarousel/

https://github.com/jsor/jcarousel/issues


2 CONTENTS

CHAPTER

ONE

REFERENCE

1.1 Installation

To use the jCarousel component, include the jQuery library and the jCarousel source file 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.

3

http://jquery.com


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 Configuration for all available configuration 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 Configuration

jCarousel accepts the following options:

See Also:

Setup Set configuration options on initialization.

reload method Set configuration 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);

}

4 Chapter 1. Reference


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 asinteger (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 user’s browser supports transitions and/or transforms. You haveto do that yourself when setting the option.You can for example use Modernizr for browser feature detection. If you’re not including it already in yoursite, you can use this minimal build.

Example:

$(’.jcarousel’).jcarousel({’transitions’: true

});

$(’.jcarousel’).jcarousel({transitions: Modernizr.csstransitions ? {

transforms: Modernizr.csstransforms,

1.2. Configuration 5

http://api.jquery.com/animate

http://api.jquery.com/animate/#animate-properties-options

https://developer.mozilla.org/en-US/docs/CSS/transition-timing-function

http://modernizr.com

http://modernizr.com/download/#-csstransforms-csstransforms3d-csstransitions-teststyles-testprop-testallprops-prefixes-domprefixes


transforms3d: Modernizr.csstransforms3d,easing: ’ease’

} : false});

Default: false

wrap Specifies whether to wrap at the first 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 Specifies whether the carousel appears in vertical orientation. Changes the carousel from a left/right styleto a up/down style carousel.

If set to null, jCarousel tries to auto-detect the orientation by simply checking if the list’s height is greater thanthe list’s width.

Example:

$(’.jcarousel’).jcarousel({’vertical’: true

});

Default: null

rtl Specifies 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 Specifies wether the targeted item should be centered inside the root element.

Warning: This feature is experimental and may not work with all setups.



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 specific item or relativeby a given offset (See section Available formats for the target argument for more information about the targetargument).

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 finished.

The function receives as first 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 thecarousel if you have changed the content of the list from the outside or want to change options that affectappearance of the carousel at runtime.

Example:

$(’.jcarousel’).jcarousel(’reload’, {’animation’: ’slow’

});

.jcarousel(’destroy’) Removes the jCarousel functionality completely. This will return the element back toits initial state.

Example:

1.3. API 7


$(’.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. Thatmeans 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 first 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’);



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 first 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 navigationcontrols 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 9


-=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 Defining the number of visible items

You simply define the number of visible items by defining the width (or height for a vertical carousel) of the rootelement (if you use the default from this document, you do that with the class .jcarousel in your stylesheet).

This offers a lot of flexibility, because you can define the width in pixel for a fixed carousel or in percent for a flexiblecarousel.

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 root’s 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 elements’s height is greater than the listelement’s width.

If auto-detection doesn’t work, you can explicitly pass the vertical option:


$(’.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 valuertl on the root or any of its parent elements.

<div class="jcarousel" dir="rtl"><ul>

</ul>

</div>

If auto-detection doesn’t 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 float 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() {// Don’t do that$(’.jcarousel li:eq(0)’)

.replaceWith(’<li class="myclass">Item 1</li>’);

// Do this

1.4. Usage 11


$(’.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 youinitialize 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

});



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 finished.

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’).on(’animate.jcarousel’, function(event, carousel) {// "this" refers to the root element// "carousel" is the jCarousel instance

});

animateend.jcarousel Triggered after the carousel has finished 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 first 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 first 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

});



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

CHAPTER

TWO

PLUGINS

2.1 Plugins

By default, the jCarousel core only contains the minimum functionality needed to built carousel widgets. Specializedfeatures 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:

<div>

<div class="jcarousel">

<ul><li>...</li><li>...</li>

</ul></div>

<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:


$(’.jcarousel’).jcarousel({// Core configuration goes here

17


});

$(’.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 isn’t 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>

Configuration

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 from theScrollIntoView Plugin.

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

18 Chapter 2. Plugins


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 reinitializethe 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 elementback 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 you’re at the last item in this case).

If the target option is absolute, 0 for example (always scrolls to the first item), the control is active if the targeteditem is at position 0, inactive otherwise.

2.1. Plugins 19


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

});


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:

<div>

<div class="jcarousel">

<ul><li>...</li><li>...</li>

</ul></div>

<div class="jcarousel-pagination">

</div>

</div>



$(’.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 thecarousel.

This works best if you enclose the carousel and its pagination inside a mutual wrapper element.

If that fails or isn’t 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


Configuration


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


.jcarouselPagination(’reload’ [, options]) Reloads the plugin. This method is useful to reinitial-ize the plugin or if you want to change options at runtime.

Example:

$(’.jcarousel-pagination’).jcarouselPagination(’reload’, {’interval’: 1500

});



.jcarouselPagination(’destroy’) Removes the pagination functionality completely. This will return theelement 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


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 onthe fly depending on your configuration.

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.



$(’.jcarousel’).jcarousel({

// Core configuration goes here}).jcarouselAutoscroll({

// Plugin configuration goes here});

});</script>



Configuration


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


.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 reinitial-ize 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 returnthe element back to its initial state.

2.1. Plugins 25


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.



API

The plugin exposes the following method:

.jcarousel(’scrollIntoView’, target [, animate [, callback]]) The arguments are simi-lar to the scroll() method.

If the targeted item is currently not fully visible, it will be the first or last fully visible item after calling themethod.

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

CHAPTER

THREE

COOKBOOK

3.1 How to define a custom start position

Sometimes, you don’t want to start your carousel at the first item but define a custom start position.

This can be achieved in two ways: Either by listening to the createend event or by defining the start position viaCSS.

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 figure out which item to use as the startitem:

.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


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

http://jquery.com

http://billwscott.com/carousel/

http://looksgoodworkswell.com


32 Chapter 4. Credits

CHAPTER

FIVE

LICENSE

Copyright 2013 Jan Sorgalla. Released under the MIT license.

33

https://github.com/jsor/jcarousel/blob/master/LICENSE

j carousel

Documents

jcarousel ul

jcarousel component

jcarousel li

jcarousel documentationrelease

setupto setup jcarousel

jcarousel source file

list element

list of items