Sky jQuery Touch Carousel Documentation (v1.0.2)

Getting Started

Before you start, let's take a look at the files and folders in the package. The main directory contains the example files and other type of resources. The following section describes the directories and files located under the main directory.

Introducing the Files

  • /source

    The source directory contains all of the necessary files to deploy the plugin.

    • /js

      The js directory contains all of the JavaScript files for the plugin. These files are;

      • jquery-1.9.1.min.js

        The core jQuery library. Visit http://www.jquery.com for more information.

      • jquery.sky.carousel-1.0.2.min.js

        The main JavaScript file for Sky jQuery Touch Carousel.

    • /css

      The css directory contains the stylesheet files for the plugin.

    • /images

      The images directory contains the images for the skin files and examples.

      • /sc-graphics

        Contains the image files for the skins.

    • Example HTML files

      Contains the example HTML files that you can play around to learn the general usage of the plugin.

  • /src

    The src directory contains the source files for the plugin. You don't need to use them if you're not planning to modify the source code.

  • /documentation

    The documentation directory contains the help file as a simple HTML file.

  • /psd-photoshop

    The psd-photoshop directory contains the original photoshop files for some skins.

  • /build

    The build directory contains a batch file to build a single JavaScript file out of the source files. In addition, it contains a compiler.jar file which is required during creating the minimal version of the plugin. The compiled version of the plugin can be created by double clicking on the build.bat file. See https://developers.google.com/closure/compiler/ for more information.

Include the Files

You need to add the following javascript and css files into your header. Add the files in this order to avoid unexpected problems.

<link type="text/css" rel="stylesheet" href="css/default_skin.css" />
<script type="text/javascript" src="js/jquery-1.9.1.min.js"></script>
<script type="text/javascript" src="js/jquery.sky.carousel-1.0.2.min.js"></script>

Create HTML Markup

You should start creating your markup with a main DIV that has .sky-carousel as a css class. There should be another DIV called .sky-carousel-wrapper under the main DIV. Under the .sky-carousel-wrapper DIV, there will be an unordered list called .sky-carousel-container. It will hold the carousel items.

Each list item under the .sky-carousel-container represents a carousel item. Each carousel item contains an <img> tag, followed by a DIV called .sc-content. The <img> tag should point to the carousel image and the .sc-content DIV should contain the content for that particular carousel item. The tags that should be used in .sc-content are <h2> and <p> respectively. You can add your own markup inside the <p> tag.

Have a look at the code below to understand the use:

<div id="your-carousel-id" class="sky-carousel">
	<div class="sky-carousel-wrapper">
		<ul class="sky-carousel-container">
			<li>
				<img src="images/1.png" alt="" />
				<div class="sc-content">
					<h2>Peter Bell</h2>
					<p>Software Developer</p>
				</div>
			</li>
			<li>
				<img src="images/2.png" alt="" />
				<div class="sc-content">
					<h2>Adam Rose</h2>
					<p>Graphic Designer</p>
				</div>
			</li>
			<li>
				<img src="images/3.png" alt="" />
				<div class="sc-content">
					<h2>Josh Coil</h2>
					<p>Chief Editor</p>
				</div>
			</li>							
			<li>
				<img src="images/4.png" alt="" />
				<div class="sc-content">
					<h2>Richard Will</h2>
					<p>Support Manager</p>
				</div>
			</li>
			<li>
				<img src="images/5.png" alt="" />
				<div class="sc-content">
					<h2>Steve Goldman</h2>
					<p>Marketing Manager</p>
				</div>
			</li>
		</ul>
	</div>
</div>

Initializing the Plugin

Initializing the plugin is pretty simple. Just add the following code piece at the end of your header. See the examples files in the package to learn how to use additional settings.

If you are unfamiliar with jQuery, please see this tutorial: http://docs.jquery.com/Tutorials:How_jQuery_Works

$(function() {
	$('#your-carousel-id').carousel({
		itemWidth: 200, // The width of your images.
		itemHeight: 350 // The height of your images.
	});
});

Changing the Size

The size of the carousel can be set through CSS. Open the CSS file with your text editor, find the CSS definition for .sky-carousel class and set the dimensions that you like.

You can ignore the width or set it in percentage if you want the carousel to fit into the surrounding container. To set a fixed width just add a width value in px.

.sky-carousel {
	width: 100%; // Set it in px for a fixed width
	height: 450px;
}
					

If you don't want to edit the original skin files, you can always add a CSS definition into your own stylesheet file as in the following example.

#your-carousel-id {
	width: 100% !important;
	height: 450px !important;
}
					

Using the Skins

The plugin comes with several skin files that you can switch between. Each skin file has its own CSS definitions inside a separate file. Changing a skin is easy, just include the related CSS file into your header. Remember that there is no such thing called base CSS in Sky jQuery Touch Carousel. Each skin file also contains the base CSS definitions for the plugin so you don't have to include another stylesheet.

You can select between one of these skin files and add it into the head section:

<link href="css/default_skin.css" type="text/css" rel="stylesheet" />
<link href="css/default_skin_variation.css" type="text/css" rel="stylesheet" />
<link href="css/tooltip_skin.css" type="text/css" rel="stylesheet" />
<link href="css/tooltip_skin_variation.css" type="text/css" rel="stylesheet" />

Modifying the Appearance

You can change the visual appearance of the plugin through CSS. Just copy one of the skin files and start modifying it to match your target design. Alternatively, you can override the existing CSS definitions in your own CSS files.

Plugin Options

There are several useful configuration parameters that you can use to change the default behavior of the plugin.

Parameter Default Description
itemWidth 300 The width of the carousel item images.
itemHeight 450 The height of the carousel item images.
distance 15 The distance between the carousel items.
startIndex 'auto' The index of the carousel item to show at start-up. Use 0 for the first item and 'auto' for the middle.
enableKeyboard true If it's set to true, you can use the direction keys on your keyboard to navigate between the carousel items.
enableMouseWheel true If it's set to true, you can use the mouse wheel to switch between the carousel items.
reverseMouseWheel false Indicates whether the direction of the mouse wheel navigation will be reversed.
autoSlideshow false Indicates whether to display the items in auto slideshow mode.
autoSlideshowDelay 2.5 The number of seconds to wait for each carousel item during auto slideshow mode.
loop true If it's set to true, the auto slideshow returns to the first item after showing the last one. This option only works when the autoSlideshow parameter is set to true.
selectedItemDistance 50 The distance between the currently selected item and other items.
selectedItemZoomFactor 1.0 The scale factor for the currently selected item. It should be equal to or less than 1.0.
unselectedItemZoomFactor 0.6 The scale factor for the unselected items. It should be equal to or less than 1.0.
unselectedItemAlpha 0.6 The opacity of the unselected carousel items.
motionStartDistance 150 The distance between the center and the place on each side where item scaling and other property updates will begin changing. (Such as opacity, scale)
topMargin 30 The distance between the top of the plugin and the currently selected item.
preload true Indicates whether to preload all of the items at start and then start the plugin.
showPreloader true Indicates whether a preloader will be shown while loading the images.
navigationButtonsVisible true Indicates whether the navigation buttons will be visible.
gradientStartPoint 0.15 The color start point for the gradient overlays. It should be between 0 and 1.0
gradientEndPoint 1.0 The color end point for the gradient overlays. It should be between 0 and 1.0
gradientOverlayVisible true Indicates whether the gradient overlays will be visible.
gradientOverlayColor '#fff' The color of the gradient overlays.
gradientOverlaySize 215 The width of the gradient overlays.
reflectionVisible false Indicates whether the item image reflection will be visible.
reflectionDistance 4 The distance between the image and the reflection.
reflectionSize 100 The height of the reflection.
reflectionAlpha 0.38 The opacity of the reflection.
slideSpeed 0.45 The slide transition speed in seconds.
selectByClick false Indicates whether a carousel item can be selected with a single click.

Advanced Usage

The plugin API offers very useful methods and events for advanced JavaScript and jQuery developers. The current API includes methods for selecting individual items and controlling the auto slideshow. There are also several events which can be used to be notified when a certain thing happens. A full list of the available methods and events can be found below:

Methods:

/**
 * Starts the auto slideshow.
 */
startAutoSlideshow();

/**
 * Stops the auto slideshow.
 */
stopAutoSlideshow();

/**
 * Selects the given item.
 * 
 * @param {Number | CarouselItem} arg The item index or the actual item to be selected.
 * @param {Number} duration Indicates the duration that the selection animation will take.
 */
select(arg, duration);

/**
 * Selects the next carousel item in the queue.
 * @param {Number} duration Indicates the duration that the selection animation will take.
 */
selectNext(duration);

/**
 * Selects the previous carousel item in the queue.
 * @param {Number} duration Indicates the duration that the selection animation will take.
 */
selectPrevious(duration);

Events:

itemSelected.sc // Dispatched when a carousel item is selected.
closestItemChanged.sc // Dispatched when the closest item to the center has been changed.
selectionAnimationStart.sc // Dispatched when the selection animation has started.
selectionAnimationEnd.sc // Dispatched when the selection animation has ended.
					

Examples:

<script type="text/javascript">
	$(function() {
		// Acquire a reference to the carousel
		var carousel = $('#your-carousel-id').carousel({
			itemWidth: 300,
			itemHeight: 450,
			distance: 15,
			selectedItemDistance: 50
		});
		
		// Select the 2nd item with 4 second selection animation
		carousel.select(2, 4);
		
		// Select the next item with no animation
		carousel.selectNext(0);
		
		// Select the previous item with 2 second selection animation
		carousel.selectPrev(2);
		
		// Start auto slideshow
		carousel.startAutoSlideshow();
		
		// Stop auto slideshow
		carousel.stopAutoSlideshow();
		
		// Print the selected item's index to the console
		carousel.on('itemSelected.sc', function(evt) {
			console.log(evt.item.index());
		});
		
		// Print the closest item's index to the console
		carousel.on('closestItemChanged.sc', function(evt) {
			console.log(evt.item.index());
		});
		
		// Append some text to the body when the selection animation has started
		carousel.on('selectionAnimationStart.sc', function(evt) {
			$('body').append('<p>Animation has started...</p>');
		});
		
		// Append some text to the body when the selection animation has ended
		carousel.on('selectionAnimationEnd.sc', function(evt) {
			$('body').append('<p>Animation has ended...</p>');
		});
	});
</script>

If you are planning to make any modifications to the codebase. Use build.bat to create a minified and single JavaScript file. After running build.bat, you can find the compiled version under the js directory. See https://developers.google.com/closure/compiler/ for more information about the closure compiler.