Waterwheel Image Carousel Options & Configuration

<

div class="clearfix">

This carousel in particular is meant to be tinkered with extensively. There are a lot of different ways to cascade the images. If you'd like, you can even display it so it's a completely flat 2-D carousel with no image resizing.


Below is a list of all the configurable options. I tried to give a good description to each, but if something is not clear, feel free to drop me an email or comment on the carousel's main page.

Option Description Type Default
startingItem Determines which image will appear in the center when the carousel loads. Set to 0 to start with the middle item. integer 0
separation The amount if pixels to separate each item from one another. integer 150
separationMultiplier Multiplied by 'separation' exponentially to determine item separation for all items (a value of 0.5 will reduce the distance by half for each item as they span out). integer 0.6
horizonOffset The amount of pixels to separate each item from the horizon. Can be negative or positive to have the items fall above or below horizon. Set to '0' to keep the center of each item aligned with the horizon. integer 0
horizonOffsetMultiplier Multiplied by 'horizonOffset' exponentially to determine horizon offset for all items. integer 0.7
sizeMultiplier How much the items should increase/decrease by as they span out (a value of 0.5 will reduce each items size by half). integer 0.7
opacityMultiplier How drastically the opacity of each item decreases. Applied exponentially.  integer 0.8
horizon How "far in" the horizon should be set from either the top of the container (horizontal orientation) or left of the container (vertical orientation). By default, it will be centered based on the container dimensions. integer 0
flankingItems The amount of visible images on either side of the center item at any time. integer 3
speed Time in milliseconds it takes to rotate the carousel. integer 300
animationEasing The easing effect used to animate the features in the carousel. jQuery has two built in effects 'swing' and 'linear'. There are many more transition effects available with this plugin. string 'linear'
quickerForFurther Will animate the carousel faster depending on how far away an item was when it was clicked to move to center. boolean true
edgeFadeEnabled When true, items fade off into nothingness when reaching the edge. Otherwise, they will move to a hidden position behind the center item. boolean false
linkHandling Determines behavior of links that are placed around the images. 1 to disable all (if you want to use the callback functions to do something special with the links), 2 to disable all but center (to link images out) integer 2
autoPlay The speed in milliseconds to wait before auto-rotating. Positive value for a left to right movement, negative for a right to left. Zero to turn off. integer 0
orientation Controls whether or not the carousel spans out horizontally or vertically. The default options are optimized for a horizontal orientation. string 'horizontal'
activeClassName The class name to assign to the item currently in the center position. string 'carousel-center'
keyboardNav Set to true to allow the user to use the arrow keys to move the carousel. boolean false
keyboardNavOverride Set to true to to override the normal functionality of the arrow keys on the browser window (prevents scrolling of the window). False to allow normal functionality of the keys as well as controlling the carousel. boolean true
imageNav When true, clicking an image that is not in the center position will rotate the image to the center. False to disable that functionality, which is commonly paired with navigational buttons instead. boolean true
preloadImages The carousel will attempt to preload all images before initializing. This is known to have some issues in certain browsers. The main reason for the preloader is too be able to determine the dimensions for each image before running calculations. If you run into issues, disable this and use the forced proportions below (or set your image dimensions using CSS). boolean true
forcedImageWidth Set a global width that should be applied to all images in the carousel. integer 0
forcedImageHeight Set a global height that should be applied to all images in the carousel. integer 0
movingToCenter Callback function fired when an item is moving to the center position. function empty
movedToCenter Callback function fired when an item has moved to the center position. function empty
clickedCenter Callback function fired when a user has clicked the center item. function empty
movingFromCenter Callback function fired when an item is moving away from the center position. function empty
movedFromCenter Callback function fired when an item has moved from the center position. function empty

API Functions

To use these functions, you should assign the carousel to a local variable. For instance, you could initialize the carousel like this: var carousel = $('#carousel').waterwheelCarousel();. Then the functions on the carousel can be called like this: carousel.next().

Function Name Description
next() Rotate the carousel one position to the next position.
pev() Rotate the carousel one position to the previous position.
reload(options) Re-initialize the carousel. This could be used if you add or remove items to the carousel and need it to 'reset' to reflect any changes. Optionally pass in a new object of options that will be used to customize the carousel. If none are passed, the previously used options are used.

Further explanation of callback functions

These functions are what really make the carousel useful, but may be tough to understand for people not used to the concept. Instead of a normal integer or string value passed in as an option, you are passing in a callback function. The function takes has parameter, which the carousel will use to place data about the image that was clicked. When certain events happen, the carousel will call the passed in function, passing in the item object. Here is an example:

$(document).ready(function () {
  $("#waterwheelCarousel").waterwheelCarousel({
    clickedCenter: function($clickedItem) {
      // $clickedItem is a jQuery wrapped object describing the image that was clicked.
      var imageUrl = $clickedItem.attr('src');
      alert('The center image was just clicked. The URL of the image is: ' + imageUrl);
    },
    movedToCenter: function($newCenterItem) {
      // $newCenterItem is a jQuery wrapped object describing the image that was clicked.
      var imageID = $newCenterItem.attr('id'); // Get the HTML element "id" for this image. Let's say it's "tigerpicture"
      // Now that we have the ID of the image, we can use jQuery to show the content corresponding to the tigerpicture.
      $('#'+imageID+'-information').show(); // this will show the HTML element with id of "tigerpicture-information" on your site.
    }
  });
});

This can be a bit confusing at first, but these functions will let you be very flexible with what the carousel can show/hide/load onto your site. If you wrap images with links, you can access the link simply by using $clickedItem.parent() or $newCenterItem.parent() (from the above example).

Further explanation of "linkHandling"

You can wrap all of the images in links if you'd like. Most people will probably want to add links around each image, but only activate the links when the center item is clicked. This is the default use case. However, you can turn all of the links off if you prefer using the callback functions to handle the links.