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

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

html diagram

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.