Tips & tricks

Congifuration robot

Need help with all the configuration options? Give the configuration robot a try!

Specify the size of an image

If you're scrolling images, don't forget to specify the sizes. Otherwise Webkit browsers (Chrome and Safari) can't measure the size of the images onDocumentReady.

<img src="image1.jpg" width="140" height="140" />

#foo img {
	width	: 140px;
	height	: 140px;
}

$("#foo").carouFredSel({
	items	: {
		width	: 140,
		height	: 140
	}
});

Debug with FireFox and FireBug

The plugin logs error-messages to the FireBug console.
So if your carousel isn't doing what you expected, just open up the console and you might read: "carouFredSel: not a valid number.".
If you set the debug option for the second configuration-object to true, it will also log debugging-information to help you out.

Set a speed for the transition in stead of a duration.

Like every jQuery animation, a carousel created by the carouFredSel-plugin wil scroll for a specific amount of time, regardless of the distance, i.e. duration. This is fine if the distance is always the same, but unfortunately it isn't.
For example when your carousel contains items with variable sizes, or when you're scrolling a variable number of items.

A speed for items with variable sizes
Give the duration a numerical value less then 10 to calculate a scrolling speed based on the number of pixels to scroll. If you do so, the value will be interpreted as the amount of pixels scrolled per millisecond.
The duration will be calculated as follows: duration = distance in pixels / pixels per millisecond;.

A speed for scrolling a variable number of items
Enter duration: "auto" to calculate a scrolling speed based on the number of items to scroll.
The duration will be calculated as follows: duration = scroll.duration / scroll.items * number of items to scroll;
Note 1: You might also want to set prev.duration and next.duration to "auto" when you're using the slideTo event.
Note 2: The duration is NOT set to "auto" by default because -as mentioned- every jQuery animation uses a duration.

Options shorthand notation

Inspired by the "Write less, do more" concept, the carouFredSel-plugin options supports shorthand notation.
In the configuration, the options items, scroll, auto, prev, next and pagination can be either an object or any valid value for the most important option(s) of that object (visible or width+height for the items option, items, duration or easing for the scroll option, play or pauseDuration for the auto option, button or key for the prev and next options, container or keys for the pagination option).

For example, making the prev option an object with button: "#prev_button", has the same results as making it "#prev_button".

All possible shorthand options:

$("#foo1").carouFredSel({
	items : {
		visible : 10
	}
});

//	--------------------------------------- //

$("#foo2").carouFredSel({
	items : {
		width : "variable",
		height: "variable"
	}
});

//	--------------------------------------- //

$("#foo3").carouFredSel({
	scroll : {
		items : 2
	}
});

//	--------------------------------------- //

$("#foo4").carouFredSel({
	scroll : {
		duration : 1000
	}
});

//	--------------------------------------- //

$("#foo5").carouFredSel({
	scroll : {
		easing : "linear"
	}
});

//	--------------------------------------- //

$("#foo6").carouFredSel({
	auto : {
		play : false
	}
});

//	--------------------------------------- //

$("#foo7").carouFredSel({
	auto : {
		pauseDuration : 3000
	}
});

//	--------------------------------------- //

$("#foo8").carouFredSel({
	prev : {
		button : "#prev_button"
	},
	next : {
		button : "#next_button"
	}
});

//	--------------------------------------- //

$("#foo9").carouFredSel({
	prev : {
		key : "left"
	},
	next : {
		key : "right"
	}
});

//	--------------------------------------- //

$("#foo10").carouFredSel({
	pagination : {
		container : "#pagination"
	}
});

//	--------------------------------------- //

$("#foo11").carouFredSel({
	pagination : {
		keys : true
	}
});

$("#foo1").carouFredSel({
	items : 10
});
/*	all other options for the items-object
	will be inherited from the default values */

//	--------------------------------------- //

$("#foo2").carouFredSel({
	items : "variable"
});
/*	all other options for the items-object
	will be inherited from the default values */


//	--------------------------------------- //

$("#foo3").carouFredSel({
	scroll : 2
});
/*	all other options for the scroll-object
	will be inherited from the default values */

//	--------------------------------------- //

$("#foo4").carouFredSel({
	scroll : 1000
});
/*	all other options for the scroll-object
	will be inherited from the default values */

//	--------------------------------------- //

$("#foo5").carouFredSel({
	scroll : "linear"
});
/*	all other options for the scroll-object
	will be inherited from the default values */

//	--------------------------------------- //

$("#foo6").carouFredSel({
	auto : false
});
/*	all other options for the auto-object
	will be inherited from the scroll-object */

//	--------------------------------------- //

$("#foo7").carouFredSel({
	auto : 3000
});
/*	all other options for the auto-object
	will be inherited from the scroll-object */

//	--------------------------------------- //

$("#foo8").carouFredSel({
	prev : "#prev_button",
	next : "#next_button"
});
/*	all other options for the prev-
	and next-objects will be inherited
	from the scroll-object
*/

//	--------------------------------------- //

$("#foo9").carouFredSel({
	prev : "left",
	next : "right"
});
/*	all other options for the prev- 
	and next-objects will be inherited 
	from the scroll-object
*/

//	--------------------------------------- //

$("#foo10").carouFredSel({
	pagination : "#pagination"
});
/*	all other options for the pagination-object
	will be inherited from the scroll-object */

//	--------------------------------------- //

$("#foo11").carouFredSel({
	pagination : true
});
/*	all other options for the pagination-object
	will be inherited from the scroll-object */

Controlling the carousel externally with anchor-links

It is very easy to externally control a carousel, just have a look at the custom events-page.
But it's even easier; any link (<a>-tag) on your page can be turned into a link that externally controlls the carousel. Simpy set the href to the item's ID and set the class to "caroufredsel".

<a href="#carousel_item_id" class="caroufredsel">click to slide</a>

If you do so, clicking the link will automatically slide the carousel to the item with id="carousel_item_id".
If you want to customize this functionality, have a look at the linkAnchors custom event.

How the pagination handles half filled pages

The image-carousel examples on this website contain 12 images and show 5. If the carousel is circular, this will result in the following set of pages:

Page 1:

• 1
• 2
• 3
• 4
• 5

1 1 1

Page 2:

• 6
• 7
• 8
• 9
• 10

1 1 1

Page 3:

• 11
• 12
• 1
• 2
• 3

1 1 1

As shown above, because the number of total items is not a multiplication of the visible items, the third page is a half filled page and also shows three items of the first page. In this case, combining the pagination with previous- and next-buttons, might cause the pagination to function odd or in an unexpected way. But in fact, it does work correctly.

Building a custom pagination

By default, the plugin uses the public function $.fn.carouFredSel.pageAnchorBuilder to build the pagination-anchors:

$.fn.carouFredSel.pageAnchorBuilder=function(nr, item) {
	var str  = '<a href="#">';
		str += '<span>'+nr+'</span>';
		str += '</a>';
	return str;
}

<div id="pagination">
	<a href="#"><span>0</span></a>
	<a href="#"><span>1</span></a>
	<a href="#"><span>2</span></a>
	<a href="#"><span>3</span></a>
</div>

To build a custom pagination, simply override this function in the configuration:

$("#foo").carouFredSel({
	pagination : {
		container		: "#pagination",
		anchorBuilder	: function(nr, item) {
			return "<div>"+nr+"</div>";
		}
	}
});

<div id="pagination">
	<div>0</div>
	<div>1</div>
	<div>2</div>
	<div>3</div>
	<div>4</div>
	<div>5</div>
</div>

Note: Every direct descendant of the pagination.container element will become an anchor for the pagination,
it does not need to be a link (a element) nor does it need the href attribute.

Carousel wrapped inside a wrapper

After the plugin has been executed, the container-element has been wrapped inside a div-element with class="caroufredsel_wrapper".
This is needed to hide items until they come scrolling in (and for the scrolling itself).

<div class="image_carousel">
	<div class="caroufredsel_wrapper">
		<div id="foo">
			<img src="image1.jpg" />
			<img src="image2.jpg" />
			<img src="image3.jpg" />
		</div>
	</div>
	<div class="clearfix"></div>
</div>

.caroufredsel_wrapper {
	width: 100;	/* calculated on the fly */
	height: 50;	/* calculated on the fly */
	position: relative;
	overflow: hidden;
}
#foo {
	width: 300;	/* calculated on the fly */
	position: absolute;
}

Preventing F.O.U.C.

When using the carouFredSel-plugin, you may see a Flash Of Unstyled Content (F.O.U.C.). This is because the browser may render elements before the DOM is fully loaded and before the DOMContentLoaded event is fired.
Fortunately it can be prevented, pretty easy actually. Simply apply something like the following CSS to your HTML element.

#foo {					/*	the HTML element that will be turned into a carousel */
	width: 870px;		/*	depending on your situation */
	height: 175px;		/*	depending on your situation */
	overflow: hidden;
}

Make the items float left

Divs are block-elements by default, so they'll be stacked beneath each other.
Give them the CSS property float: left; to make them float next to each other.

<div class="image_carousel">
	<div id="foo">
		<img src="image1.jpg" />
		<img src="image2.jpg" />
		<img src="image3.jpg" />
		<img src="image4.jpg" />
	</div>
	<div class="clearfix"></div>
</div>

.image_carousel img {
	border: none;
	display: block;
	float: left;
}
div.clearfix {
	float: none;
	clear: both;
}