jCarrtCell Documentation

Configurations

Example of a carrotCell object with configurations:


var myCarouselAPI = $('#myCarousel').carrotCell({
	sideways: false,
	delay: 3000,
	key: true,
	navi: true,
	step:1,
	auto: true
});

Basic Configuration

The configuration options are passed into the carrotCell as an object on creation.

Config Property	Property Type	Example	Description	Default
step	integer	5	How many items to advance by, if not set, the items to advance by is assumed to be all current visible elements in the container. Step should be smaller than the number of total items and smaller than or equal to all visible elements in the container.	Number of visible items
sideways	boolean	false	By default makes a horizontal scroller. Set to false to create a vertical or up and down scroller. Note your CSS must support this layout.	true
infinite	boolean	true	On reaching the end of the carousel, show from start again without rewinding.	false
auto	boolean	true	Make the carousel automatically scroll forward on a timer. This will make the carousel infinite by default.	false
delay	integer (milisecs)	9000	The time delay between auto scrolling of each page.	5000
speed	integer (milisecs)	9000	The speed at which the carousel does its scroll animation.	500
navi	boolean	true	Indicate that an external navigation is included. The number of navi items created must correspond to the number of pages used if not using makeNavi. There must be an element of class .navi in the HTML with direct descendent children used as each navigation item inside.	false
makeNavi	boolean	false	Generate the paging navigation automatically. The container for navi must already exist and have the .navi class.	false
stopOnClick	boolean	true	Stop auto advance when a navi element is clicked.	false
pauseOnHover	boolean	true	Stop auto advance when the mouse is hovering over the carousel.	false
key	boolean	true	Turn on or off arrow key navigation for carousel. Up and Down arrows work for vertical carousels, and Left and Right arrows for horizontal. Note that since key events are document based all carousels would recognize the event.	false
containsControl	boolean	false	Indicates wether the carrotCell controls are contained inside .carrotCell or elsewhere in the DOM. Set the property controlScope (see below for Selector Configurations) to designate a new scope If there is no controlScope set, the body is assumed to be the new scope of controls.	true
carrotDone	function	`carrotDone: function(api){ api.whichCarrot() }`	A custom call back after the carrotCell has been initialized. By default it is passed the API object of the carrotCell.

Class Configuration

Some default utility class names can be changed by passing in a new class name. This property does not accept selectors, only string class names. These settings are also passed in on creation of the carrotCell object.

Config Property	Example	Description	Default
disabledClass	"off"	The class added to previous and next when no action is possible. This is added to the controls when the end of the list of items is reached.	"disabled"
currentClass	"on"	The classname for the currently selected child of the navi.	"current"
cloneClass	"twin"	The classname for the currently selected child of the navi.	"clone"
naviClass	"dot"	The classname for the individual navi page items.	"naviItem"

Events

Event names can be customized for versatility. The Event Literal is passed by the event information object to help identify what the original event is despite any name changes.

Setting Name	Description	Event Default Name	Event Literal	Values Returned
scrollStart	Signal that the carousel has started its scrolling animation.	"carrotScrollStart"	"scrollStart"	carrotCellName, eventLiteral, currentPageNumber
scrollEnd	Signal that the carousel has ended its scrolling animation.	"carrotScrollEnd"	"scrollEnd"	carrotCellName, eventLiteral, currentPageNumber
atStart	Signal that the carousel has reached its starting point.	"carrotAtStart"	"atStart"	carrotCellName, eventLiteral,
atEnd	Signal that the carousel has reached its ending point.	"carrotAtEnd"	"atEnd"	carrotCellName, eventLiteral,
onPlay	Signal that the carousel is currently on auto scroll.	"carrotPlay"	"onPlay"	carrotCellName, eventLiteral,
onPause	Signal that the carousel is currently paused on auto scroll.	"carrotPause"	"onPause"	carrotCellName, eventLiteral,
onStop	Signal that the auto scroll on carousel is currently disabled.	"carrotStop"	"onStop"	carrotCellName, eventLiteral,
onInsert	Something has been inserted into the carrotCell.	"carrotInsert"	"insert"	carrotCellName, eventLiteral, totalPages
onRemove	A carrotCell item has been removed.	"carrotRemove"	"remove"	carrotCellName, eventLiteral., totalPages
onEmpty	The carrotCell now contains no items.	"carrotEmpty"	"empty"	carrotCellName, eventLiteral
onReload	The carrotCell has been reloaded with completely different content	"carrotReload"	"reload"	carrotCellName, eventLiteral, pages
pagesChanged	The number of pages have changed based on insert, remove, or reload.	"carrotPageCountChanged"	"pagesChanged"	carrotCellName, eventLiteral, currentPageCount, previousPageCount

Selector Configuration

Default selectors can be over-ridden by passing in a new jQuery selector string. Note that most selectors operate inside .carrotCell unless the controlScope and the containsControl property.

Config Property	Scope	Example	Description	Default
sliderSelect	.carrotCellView	"div"	This contains all the slides and is inside .carrotCellView. This selector selects the first encountered selection Only the first div inside .carrotCellView is selected in the example case.	"ol"
sliderChildSelect	sliderSelect	"div"	This is the child slide of Slider and is contained in sliderSelect This selector selects all children of this type inside sliderSelect	"li"
controlScope	"body" or custom	"#controlUnit"	This is the scope where the carrotCell controls live. It will only be used if containsControl is set to TRUE. If containsControl is set to TRUE and no controlScope is provided, the default is "body"	current ".carrotCell"
prevSelect	controlScope	"#controlUnit .previously"	Advance the carrotCell backward if applicable	".prev"
nextSelect	controlScope	"article .nextly"	Advance the carrotCell forward if applicable	".next"
pauseSelect	controlScope	"#controlUnit .pause"	Pause the autoplay.	".pause"
playSelect	controlScope	"#play"	Resume the autoplay.	".play"
stopSelect	controlScope	"section .stop"	Stop the autoplay.	".stop"
naviSelect	controlScope	"#navigation li.naviThing"	The selection of individual clickable items inside the navi that advances the pages as determined by step parameter of the carousel.	"> *"
naviContainer	controlScope	".myspecialnavi"	The container that houses the navi.	".navi"

Inline Configuration

Config Property	Example	Description	Default
naming the navi items in makeNavi mode	<div class="navi" data-navi='["item 1", "item 2"]'></div>	Instead of the default 1...n add names to the navi individual items by passing it as a data attribute. If only 2 names are passed and there are 4 pages, it will appear as "item 1, item 2, 3, 4, 5" etc with the passed in transposed over the default.	1,2,3...n

Config Property

Example

Description

Default

naming the navi items in makeNavi mode

Instead of the default 1...n add names to the navi individual items by passing it as a data attribute.

If only 2 names are passed and there are 4 pages, it will appear as "item 1, item 2, 3, 4, 5" etc with the passed in transposed over the default.

1,2,3...n

API Methods

First retrieve the carrotCell API from the carousel created, then call any of the available API methods.


var myCarrot = $('#someCarrotCell').carrotCell(); 
var myAPI = $(myCarrot).data('carrotCell');
myAPI.moveToPage(4);

Method Name	Parameters	Return Value	Event	Description
forward			scrollStart, scrollEnd	Move the carousel forward by 1 page.
backward			scrollStart, scrollEnd	Move the carousel backward by 1 page.
moveToPage	pageNumber (integer)		scrollStart, scrollEnd	Move to page n of the carousel. If n is out of range, go to either page 1 or last page.
play			onPlay	Auto advance the carousel in auto scroll.
pause			onPause	Pause the carousel during auto scroll.
stop			onStop	Stop the carousel from auto scrolling.
insert	item (string), index (integer)	totalItems (integer)	onInsert	Insert the new carousel element at a certain index. If there is no index, the index is assumed to be the index of the last item. If the index is smaller than 0, it is assumed to be 1. if the index is bigger than the maximum number of items, index is assumed to be the last item index.
remove	index (integer)	totalItems (integer)	onRemove	Remove a carousel item at position index. If there is no index, the index is assumed to be the index of the last item. If the index is smaller than 0, it is assumed to be 1. if the index is bigger than the maximum number of items, index is assumed to be the last item index.
empty			onEmpty	Remove all carousel items.
reloadWith	newItems (string)	pages (integer)	onReload	Load a new set of slides into the carousel, completely removing previous content.
updateNavi				Re-examining the existing navi created by the user and assign handlers appropriately.
getName		name(string)		Returns the name of the carrotCell object
getPageCount		pages (integer)		Returns how many pages this carrotCell has.
getTotalItems		totalItems (integer)		Returns how many total items this carrotCell contains, not counting clones.
getSettings		settings (object)		Returns the entire settings object.
getOpenSpot		hasOpenSpot (integer)		Returns how many slots are left open in one page of the carrotCell.

HTML & CSS

1. .carrotCell contains a single carrotCell and all its components.

2. .carrotCellView class is the view area of the carousel, clipping the extra elements of the content list from being seen.

3. Parent container of the content list, usually an OL or UL.

4. Individual container of the content list, usually a LI.

5. The previous and next buttons are inside .carrotCell but not .carrotCellView, assign styles to .disabled to hide the buttons when they are not operational. By default they are positioned absolutely relative to .carrotCell.

6. Play, Pause, Stop buttons of the auto advance.

7. .navi element contains items corresponding to the pages of the carrotCell.

Known Issues

Note. There is sometimes a bug in Chrome where document ready would fire before the elements are rendered with the correct height, here is an alternate version of step 5 that fixes the problem.


$(document).ready(function(){
	window.someNameSpace = window.someNameSpace || {};
	someNameSpace.setup = function() {
		$('.carrotCell').carrotCell();
	}

	var is_chrome = navigator.userAgent.toLowerCase().indexOf('chrome') > -1;
	if (is_chrome) {
		$(window).load(function(){ someNameSpace.setup(); });
	} else {
		someNameSpace.setup();
	}
});

Implementation Notes

Nested Carousels - It is possible to nest one carousel inside another, you will have to specify the navi, previous and next selectors with a specific selector so it does not retrieve the parent's controls along with the nested carousel's controls.

Global Key Events - If you allow keyboard control of a carousel, note the event listener is bound on the document. If you have multiple carousels on the page, there is no good way to distinguish which carousel the key event was intended for and will trigger all of them if they have key enabled.