Carousel

Documentation updated on May 29th.

Description

The Carousel widget extends the Object object. This is a large list of elements controlled by two arrows to slide the content list.

Demo

Code snippet

To make the Carousel work, you need to specify the size of the component elements by CSS, for example:

.ch-carousel-content li {
	width: 120px;
	height: 120px;
}

To create a Carousel you need a container with an unordered list inside. By adding the ch-carousel class to the container, you can avoid structure changes when widget is in creating process.

<div id="example" class="ch-carousel">
	<ul>
		<li><img src="/src/assets/ninja.png"></li>
		<li><img src="/src/assets/ninja.png"></li>
		<li><img src="/src/assets/ninja.png"></li>
		<li><img src="/src/assets/ninja.png"></li>
		<li><img src="/src/assets/ninja.png"></li>
		<li><img src="/src/assets/ninja.png"></li>
		<li><img src="/src/assets/ninja.png"></li>
		<li><img src="/src/assets/ninja.png"></li>
	</ul>
</div>

Instance component

This is the way to create a Carousel:

var foo = $("#example").carousel();

Configuration

Any widget can be configurated through parameters written in JSON. Here is an example:

var foo = $("#example").carousel({
	"bar": foobar,
	"baz": quux
});

You can see the complete list of parameters in Carousel API documentation.

Basics

Working with pages

The Carousel shows pages of elements and you can move between pages with the prev and the next methods. Also, you can move the Carousel directly to a page with the select method (before version 0.7.5, called goTo).

The itemsPerPage method (before version 0.7.4, called getItemsPerPage, allow you to know the numbers of items to be displayed on each page.

Pagination

The component has a pagination feature, which is set hidden by default, but you can make it visible.

var foo = $("#example").carousel({ "pagination": true });

Defining the amount of items in a page

To specify a max amount of items showed in each page, you can use the maxItemsconfiguration parameter (since v0.10.6):

var foo = $("#example").carousel({ "maxItems": 3 });

Changing the arrows flow

Since v0.10.6 you can configure the "next" and "previous" buttons to distribute into the Carousel's space. It can be:

• outside(default): Buttons will be on mask sides.
• over: Buttons will be over the mask.
• noneor false: No arrows.

var foo = $("#example").carousel({ "arrows": "outside" });

Events

The main widget's actions trigger custom events, which you can suscribe to execute any action.

Here is an example of the ready event, triggered when component ends its load process:

foo.on("ready", function () {
	var that = this; // Where "this" is the returned object of component
});

You can see the complete list of events in Carousel API documentation.

Learn more about events on our step-by-step guide.

Asynchronous load

Initializing the Carousel with asyncData andasyncRender configuration properties exists two ways to load items asynchronously:

asyncData

One way is to using asyncData to define the content of each item that will be load asnchronously as array:

 
var foo = $("#example").carousel({
	asyncData: [
		'<img src="a.png" alt="A" />',
		'<img src="b.png" alt="B" />',
		'<img src="c.png" alt="C" />'
	]
});

asyncRender

The second way is to using asyncData through asyncRender. This is a function that receivesasyncData content and must return a string with result of manipulate that content. This way is one that requires less HTML code.

 
var foo = $("#example").carousel({
	asyncData: [
		{"src": "a.png", "alt": "A"},
		{"src": "b.png", "alt": "B"},
		{"src": "c.png", "alt": "C"}
	],
	asyncRender: function (o) {
		return '<img src="' + o.src + '" alt="' + o.alt + '" />';
	}
});