Custom events

After the plugin has been executed, a series of custom events are available for the carousel.
With these custom events, the carousel can be controlled externally. Have a look at the custom event code examples page to see just how.

Please note:
As of version 5.0.0, manually triggering the prev, next or slideTo-events will not resume a paused carousel. Instead it will now only scroll the carousel ones, re-pausing it afterwards.

	Event ( Parameters )	Default value	Datatype	Description
>	play ( direction, delay, resumeStopped ) Click to showhide the parameters for this event.			Triggering this event will restart/resume the timeout between transitions after pausing (only applies when the carousel scrolls automatically).
(
	direction	null	String	The direction to scroll the carousel. Possible values: `"prev"` or `"next"`. If `null`, the `direction` of the configuration is inherited.
	delay	0	Number	Additional delay in milliseconds before the carousel starts scrolling. Hint: This can also be a negative number.
	resumeStopped	false	Boolean	If set to `true`, the timeout between transitions of a stopped carousel will restart.
	Note: The order of these options is not important, they are sorted automatically based on the datatype.
)
>	pause ( immediate, resume ) Click to showhide the parameters for this event.			Triggering this event will pause the timeout between transitions (only applies when the carousel scrolls automatically).
(
	immediate	false	Boolean	If set to `true`, the carousel will immediately stop scrolling.
	resume	false	Boolean	If set to `true`, the timeout will resume instead of restart.
)
>	stop ( immediate ) Click to showhide the parameters for this event.			Triggering this event will stop the carousel from scrolling. A stopped carousel can only be restarted by triggering the `play`-event with `true` as a parameter.
(
	immediate	false	Boolean	If set to `true`, the carousel will immediately stop scrolling.
)
	finish			Triggering this event will immediately finish the transition, triggering all callback-functions.
	resume			Triggering this event will immediately resume the transition.
>	prev ( options, numItems, onAfter ) Click to showhide the parameters for this event.			Triggering this event will scroll the carousel backward.
(
	options	null	Object	A map of the configuration used for the scrolling (similar to the object passed in the configuration). If `null`, the `prev` object from the configuration is used.
	numItems	null	Number	The number of items to scroll. If `null`, the value for `items` in the `options` object is used.
	onAfter	null	Function	Function that will be called right after the carousel finished scrolling. This function receives 3 parameters: oldItems: a jQuery-object of the items that were visible before scrolling. newItems: a jQuery-object of the items that are visible after scrolling. newSizes: a map of the new sizes of the carousel: `newSizes.width` and `newSizes.height` If `null`, the value for `onAfter` in the `options` object is used.
	Note: The order of these options is not important, they are sorted automatically based on the datatype.
)
>	next ( options, numItems, onAfter ) Click to showhide the parameters for this event.			Triggering this event will scroll the carousel forward.
(
	options	null		See the description for the `options`-parameter in the `prev`-custom event.
	numItems	null		See the description for the `numItems`-parameter in the `prev`-custom event.
	onAfter	null		See the description for the `onAfter`-parameter in the `prev`-custom event.
	Note: The order of these options is not important, they are sorted automatically based on the datatype.
)
>	slideTo ( destination, deviation, origOrder, options, onAfter, direction ) Click to showhide the parameters for this event.			Triggering this event will scroll the carousel to the designated item.
(
	destination (required)	null	Number	The nth item to where the carousel should scroll.
			String	A jQuery-selector of the item to where the carousel should scroll. For example: `"#foo li:first"`.
			jQuery-object	A jQuery-object of the item to where the carousel should scroll. For example: `$("#foo li:first")`.
	deviation	0	Number	Deviation of the `destination`. For example: `-2` makes the carousel not end at `destination`, but 2 items to the left of it.
	origOrder	null	Boolean	Determines if the position of `destination` is relative to the original order of the items (true) or to the current order of the items (false). If `null`, the value is determined by the given value for `destination`.
	options	null		See the description for the `options`-parameter in the `prev`-custom event.
	onAfter	null		See the description for the `onAfter`-parameter in the `prev`-custom event.
	direction	null	String	The direction to scroll the carousel. Possible values: `"prev"` or `"next"`. If `null`, the carousel will choose the shortest route.
	Note: The order of these options is not important, they are sorted automatically based on the datatype.
)
>	prevPage ( options, onAfter ) Click to showhide the parameters for this event.			Triggering this event will scroll the carousel one page backward.
(
	options	null		See the description for the `options`-parameter in the `prev`-custom event.
	onAfter	null		See the description for the `onAfter`-parameter in the `prev`-custom event.
	Note: The order of these options is not important, they are sorted automatically based on the datatype.
)
>	nextPage ( options, onAfter ) Click to showhide the parameters for this event.			Triggering this event will scroll the carousel one page forward.
(
	options	null		See the description for the `options`-parameter in the `prev`-custom event.
	onAfter	null		See the description for the `onAfter`-parameter in the `prev`-custom event.
	Note: The order of these options is not important, they are sorted automatically based on the datatype.
)
>	slideToPage ( page, options, onAfter ) Click to showhide the parameters for this event.			Triggering this event will scroll the carousel to the passed page.
(
	page	null		The page to scroll to. If `null`, the carousel will scroll to the first item of the current page.
	options	null		See the description for the `options`-parameter in the `prev`-custom event.
	onAfter	null		See the description for the `onAfter`-parameter in the `prev`-custom event.
	Note: The order of these options is not important, they are sorted automatically based on the datatype.
)
>	queue ( direction / scrolls / fn, options ) Click to showhide the parameters for this event.			Triggering this event will add a scroll in the queue to be executed after the next natural scroll. Note: The queue is only processed if the `scroll.queue` option is set to `true`.
(
	direction / scrolls / fn	null	String	The direction to scroll the carousel. Possible values: `"prev"` or `"next"`.
			Array	The queue of scrolls to set, removing all previously added scrolls.
			Function	Callback-function to get the queue. This function receives 1 parameter: queue: the queue.
	options	null	Array	An array containing the options to pass to the `prev` or `next` event (`options`, `numItems` and `onAfter`).
)
>	insertItem ( items, destination, origOrder, deviation ) Click to showhide the parameters for this event.			Triggering this event will insert item(s) into the carousel.
(
	items (required)	null	String	A string of HTML to insert into the carousel. For example: `"<li>X</li>"`
			String	A jQuery-selector of the item(s) to insert into the carousel. For example: `"#foo li:first"`
			jQuery-object	A jQuery-object of the item(s) to insert into the carousel. For example: `$("#foo li:first")`
	destination	"end"	String	The position where to insert the new item(s).
			Number	The nth item where to insert the new item(s).
			String	A jQuery-selector of the item where to insert the new item(s). For example: `"#foo li:first"`
			jQuery-object	A jQuery-object of the item where to insert the new item(s). For example: `$("#foo li:first")`
	origOrder	null	Boolean	Determines if the position of `destination` is relative to the original order of the items (true) or to the current order of the items (false). If `null`, the value is determined by the given value for `destination`.
	deviation	0	Number	Deviation of the `destination`. For example: `-2` inserts the new item(s) not at `destination`, but 2 items to the left of it.
	Note: The order of these options is not important, they are sorted automatically based on the datatype.
)
>	removeItem ( items, origOrder, deviation ) Click to showhide the parameters for this event.			Triggering this event will remove an item from the carousel.
(
	items (required)	0	Number	The nth item to be removed.
			String	A jQuery-selector of the item(s) to be removed. For example: `"#foo li:first"`
			jQuery-object	A jQuery-object of the item(s) to be removed. For example: `$("#foo li:first")`
	origOrder	null	Boolean	Determines if the position of `items` is relative to the original order of the items (true) or to the current order of the items (false). If `null`, the value is determined by the given value for `items`.
	deviation	0	Number	Deviation of the `items`. For example: `-2` doesn't remove the item at `items`, but the one that is two items to the left of it.
	Note: The order of these options is not important, they are sorted automatically based on the datatype.
)
>	onBefore ( callback / callbacks ) Click to showhide the parameters for this event.			Trigger this event to add a new function to the next `onBefore`-callback.
(
	callback / callbacks	null	Function	Function to add to the callback. This function receives 4 parameters: oldItems: a jQuery-object of the items that were visible before scrolling. newItems: a jQuery-object of the items that are visible after scrolling. newSizes: a map of the new sizes of the carousel: `newSizes.width` and `newSizes.height` duration: the duration of the transition.
			Array	An array of functions to add, removing all previously added callback functions.
)
>	onAfter ( callback / callbacks ) Click to showhide the parameters for this event.			Trigger this event to add a new function to the next `onAfter`-callback.
(
	callback / callbacks	null	Function	Function to add to the callback. See the description for the `onAfter`-parameter in the `prev`-custom event.
			Array	An array of functions to add, removing all previously added callback functions.
)
>	configuration ( option / options, value / fn, reInit ) Click to showhide the parameters for this event.			Trigger this event to dynamically get or set a configuration option.
(
	option / options	null	String	The option to set (if the second parameter is a value) or get (is the second parameter is a function).
			Object	A map of the options to set.
	value / fn	null	String	The value to set for the `option`.
			Function	Callback-function to get the value for the `option`. This function receives 1 parameter: value: the value for the `option`. Note: If the callback-function is the first parameter, `value` will be the entire configuration object.
	reInit	true	Boolean	Determines if the carousel should "re-init" (re-callculate sizes etc.).
)
>	synchronise ( options ) Click to showhide the parameters for this event.			Trigger this event to synchronise the given carousels.
(
	options	null		Any valid value for the `synchronise` option in the configuration. If `null`, the value for `synchronise` in the configuration is used.
)
>	linkAnchors ( container, selector ) Click to showhide the parameters for this event.			Trigger this event to automatically bind the `slideTo`-event to any HTML-element that links to an item inside the carousel. Note: This method is executed on every `<a class="caroufredsel">`-tag after creating the carousel and after calling the `insertItem` and `removeItem` custom events by default.
(
	container	"body"	String	A jQuery-selector of the HTML-element to search in.
	selector	"a.caroufredsel"	String	A jQuery-selector of the HTML-element to search for. For example: `"a.cfs_link"` will search for `<a class="cfs_link">`-tags.
)
	updateSizes			Trigger this event to immediately set the correct sizes to the carousel.
>	currentPosition ( fn ) Click to showhide the parameters for this event.			Triggering this event will return the position of the first visible item (the current position) in the callback-function or (when calling the `triggerHandler`-method) the return value.
(
	fn	null	Function	Callback-function to get the current position. This function receives 1 parameter: position: the current position of the carousel.
)
>	currentPage ( fn ) Click to showhide the parameters for this event.			Triggering this event will return the current page number in the callback-function or (when calling the `triggerHandler`-method) the return value.
(
	fn	null	Function	Callback-function to get the current page number. This function receives 1 parameter: page: the current page of the carousel.
)
>	currentVisible ( fn ) Click to showhide the parameters for this event.			Triggering this event will return a jQuery-object of the current visible items in the callback-function or (when calling the `triggerHandler`-method) the return value.
(
	fn	null	Function	Callback-function to get the current visible items. This function receives 1 parameter: items: the current visible items in the carousel.
)
>	slice ( start, end, fn ) Click to showhide the parameters for this event.			Triggering this event will return a jQuery-object of the matching elements in the callback-function or (when calling the `triggerHandler`-method) the return value. It's behavior is the same as jQueries slice-method if the order of the items would not have been changed by the plugin.
(
	start	0	Number	The 0-based position at which the elements begin to be selected. If negative, it indicates an offset from the end of the set.
	end	null	Number	The 0-based position at which the elements stop being selected. If negative, it indicates an offset from the end of the set. If `null`, the range continues until the end of the set.
	fn	null	Function	Callback-function to get the current visible items. This function receives 1 parameter: items: the selected items.
)
>	isScrolling ( fn ) Click to showhide the parameters for this event.			Trigger this event to find out whether the carousel is scrolling using either the callback-function or (when calling the `triggerHandler`-method) the return value.
(
	fn	null	Function	Callback-function to find out whether the carousel is scrolling. This function receives 1 parameter: isScrolling: `true` or `false`.
)
>	isPaused ( fn ) Click to showhide the parameters for this event.			Trigger this event to find out whether the carousel is paused using either the callback-function or (when calling the `triggerHandler`-method) the return value.
(
	fn	null	Function	Callback-function to find out whether the carousel is paused. This function receives 1 parameter: isPaused: `true` or `false`.
)
>	isStopped ( fn ) Click to showhide the parameters for this event.			Trigger this event to find out whether the carousel is stopped using either the callback-function or (when calling the `triggerHandler`-method) the return value.
(
	fn	null	Function	Callback-function to find out whether the carousel is stopped. This function receives 1 parameter: isStopped: `true` or `false`.
)
>	destroy ( origOrder ) Click to showhide the parameters for this event.			Remove the carousel functionality completely. This will return the element back to its pre-init state.
(
	origOrder	false	Boolean	Determines if the items should be put back in the original order (true) or stay in the current order (false).
)

Note: In all callback-functions, this refers to the HTML-element of the carousel.
Note: Using the triggerHandler-method will return the value passed in the callback-function.

How to use the custom events

To trigger any of these custom events, use the trigger function which already is available for every jQuery-object.
For example, this code will scroll the carousel forward one item at a time when clicking a button.

$(document).ready(function() {
	$("#foo").carouFredSel({
		auto: false
	});
	$("#button").click(function() {
		$("#foo").trigger("next", 1);
	});
});

Have a look at the custom event code examples page for more detailed information on how to use the custom events.
Working examples of the custom events can be found on this examples page.

More on how to use the trigger method in general can be found here and more on the triggerHandler method over here.

Need some help?

When you're in desperate need of help, you might want to visit the examples-pages or have a peak at the tips & tricks and maybe the known issues. Or -if everything else fails- try the support forum.

Feedback

Any kind of feedback is more than welcome in this forum-topic.
Thank you!

Download version 5.5.0

Custom events

How to use the custom events

Need some help?

Feedback