Thanks for purchasing TouchCarousel. If you have any questions that are beyond the scope of this help file, you've found a bug or want to suggest feature, so please feel free to email me via contact form on my profile.
All carousel files are in touchcarousel folder. First of you need to insert CSS and JavaScript files - base css file, skin css file, jQuery script and TouchCarousel script:
<!-- CSS files -->
<link rel="stylesheet" type="text/css" href="touchcarousel/touchcarousel.css" />
<!-- Skin Stylesheet -->
<link rel="stylesheet" type="text/css" href="touchcarousel/black-and-white-skin/black-and-white-skin.css" />
<!-- JS files -->
<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js"></script>
<script type="text/javascript" src="touchcarousel/jquery.touchcarousel-1.0.min.js"></script>Then add following HTML code in the body section ("black-and-white" CSS class means that slider is with black-and-white skin):
<div id="yourCarouselId" class="touchcarousel black-and-white">
<ul class="touchcarousel-container">
<!-- TouchCarousel items, place any HTML content inside them (img tag is inserted as an example) -->
<li class="touchcarousel-item">
<img src="img/test-image1.jpg" width="300" height="300" />
</li>
<li class="touchcarousel-item">
<img src="img/test-image2.jpg" width="300" height="300" />
</li>
<li class="touchcarousel-item">
<img src="img/test-image3.jpg" width="300" height="300" />
</li>
<li class="touchcarousel-item">
<img src="img/test-image4.jpg" width="300" height="300" />
</li>
<li class="touchcarousel-item">
<img src="img/test-image5.jpg" width="300" height="300" />
</li>
</ul>
</div>And finally initialize carousel:
<script>
jQuery(function($) {
$("#yourCarouselId").touchCarousel({
/* carousel options go here see Javascript Options section for more info */
});
});
</script>Take a look in "demo.html" file for better understanding of carousel structure.
Set custom width and height of carousel (width can be fluid):
<style>
#yourCarouselId {
width: 100%;
height: 400px;
}
</style>TouchCarousel plugin has four pre-build skins. To add skin just add its css class to main "touchcarousel" tag and include skin css file. Skin files can be found in "touchcarousel" folder. Each skin includes CSS, PNG and PSD file.
<!-- Black and white skin — white controls on black background. CSS class - "black-and-white". -->
<link rel="stylesheet" href="touchcarousel/black-and-white-skin/black-and-white-skin.css" />
<!-- Three-D skin — 3d-styled skin, with controls position on top left. CSS class - "three-d". -->
<link rel="stylesheet" href="touchcarousel/three-d-skin/three-d-skin.css" />
<!-- Minimal light skin — simple skin with white controls. CSS class - "minimal-light". -->
<link rel="stylesheet" href="touchcarousel/minimal-light-skin/minimal-light-skin.css" />
<!-- Grey-blue skin. CSS class - "grey-blue". -->
<link rel="stylesheet" href="touchcarousel/grey-blue-skin/grey-blue-skin.css" />You can edit these skins or create your own.
Default options and their explanations:
<script>
$("#yourCarouselId").touchCarousel({
itemsPerMove: 1, // The number of items to move per arrow click.
snapToItems: false, // Snap to items, based on itemsPerMove.
pagingNav: false, // Enable paging nav. Overrides snapToItems.
// Snap to first item of every group, based on itemsPerMove.
pagingNavControls: true, // Paging controls (bullets).
autoplay:false, // Autoplay enabled.
autoplayDelay:3000, // Delay between transitions.
autoplayStopAtAction:true, // Stop autoplay forever when user clicks arrow or does any other action.
scrollbar: true, // Scrollbar enabled.
scrollbarAutoHide: false, // Scrollbar autohide.
scrollbarTheme: "dark", // Scrollbar color. Can be "light" or "dark".
transitionSpeed: 600, // Carousel transition speed (next/prev arrows, slideshow).
directionNav:true, // Direction (arrow) navigation (true or false).
directionNavAutoHide:false, // Direction (arrow) navigation auto hide on hover.
// On touch devices arrows are always displayed.
loopItems: false, // Loop items (don't disable arrows on last slide and allow autoplay to loop).
keyboardNav: false, // Keyboard arrows navigation.
dragUsingMouse:true, // Enable drag using mouse.
scrollToLast: false, // Last item ends at start of carousel wrapper.
itemFallbackWidth: 500, // Default width of the item in pixels. (used if impossible to get item width).
baseMouseFriction: 0.0012, // Container friction on desktop (higher friction - slower speed).
baseTouchFriction: 0.0008, // Container friction on mobile.
lockAxis: true, // Allow dragging only on one direction.
useWebkit3d: false, // Enable WebKit 3d transform on desktop devices.
// (on touch devices this option is turned on).
// Use it if you have only images, 3d transform makes text blurry.
onAnimStart: null, // Callback, triggers before deceleration or transition animation.
onAnimComplete: null, // Callback, triggers after deceleration or transition animation.
onDragStart:null, // Callback, triggers on drag start.
onDragRelease: null // Callback, triggers on drag complete.
});
</script><script>
// Getting instance
var sliderInstance = $("#yourCarouselId").touchCarousel({
/* options go here */
}).data("touchCarousel");
//or
var sliderInstance = $("#yourCarouselId").data("touchCarousel");
// Public methods
sliderInstance.goTo(4); // Go to item by it's id (to #5 in example)
// Make sure that you pass integer to this function.
sliderInstance.next(); // Go to next item
sliderInstance.prev(); // Go to prev item
sliderInstance.resumeAutoplay(); // Play slideshow
sliderInstance.stopAutoplay(); // Stop slideshow
sliderInstance.updateCarouselSize(); // Update slider size, use it after you manually change slider size
sliderInstance.destroy(); // Destroy all slider events and remove slider element
sliderInstance.animateTo(-200); // Animate items container to X position (to -200px in this example).
sliderInstance.setXPos(-200); // Set X position of items container in px (to -200px in this example).
sliderInstance.getCurrentId(); // Returns first visible item id (int).
// Public properties
sliderInstance.numItems // Number of items
sliderInstance.settings // Carousel settings
sliderInstance.items // Items array
// Item strucure:
// { item: "item object", index: "item index", posX: "relative X position", width: "item width" }
// Callbacks:
onAnimStart // triggers before deceleration or transition animation.
onAnimComplete // triggers after deceleration or transition animation.
onDragStart // triggers on drag start.
onDragRelease // triggers on drag complete.
// Using callback after slider init:
sliderInstance.settings.onAnimComplete = function() {
// "this" is slider instance
console.log('Animation complete', this);
};
</script>You may add "non-draggable" CSS class to elements if you want to prevent dragging over it and allow default browser action. Always add it to input fields.
Apply margin-right to items to add spacing between them. Margin-right on last slide will be automaticaly removed.
To reduce HTTP requests, merge base CSS file and skin CSS file by copying contents of skin CSS to the end of base CSS.
Use "loopItems" js property if you want autoplay to loop.
Use "scrollToLast" js property if you want last item of carousel to scroll to the beginning of viewport.
Apply background to ".touchcarousel-wrapper" if you want it to stay while dragging, otherwise apply it to ".touchcarousel-container".
Fixed small mistakes in documentation (source files haven't changed).
TouchCarousel released.
Follow me on Twitter or CodeCanyon to get notified about carousel updates.