This jQuery plugin provides carousel functionality typical for the sites we build.
This plugin is intended for installation using the Bower package management system for Javascript libraries. From within your project directory, run the following command to install this plugin to your configured components directory:
bower install git@github.com:messagedigital/jquery-carousel.git
This component depends on the following components:
- jquery v1.9.0
The only prerequisite for elements for which the carousel is instantiated on is that the element contains at one child elements.
The child elements are assumed to be the carousel slides. If there is only one child element, the carousel will instantiate fine, but it will of course not do very much and be sort of useless.
The plugin is instantiated as follows. The options parameter can be left blank, if you want to use all of the default options:
$('.my-gallery').carousel();
The available configuration options are as follows. They are defined when instantiating the plugin. Here's an overview of all available options and their default options:
$('.gallery').carousel({
arrows : false, // Show arrow controls
indicators: false, // Show position indicators / controls
animation : 'slide', // Animation to use for moving between slides
speed : 100, // Speed in milliseconds for the animation
interval : false, // Interval in milliseconds for automatically moving between slides
flexible : true, // Determines whether the carousel has a flexible width
onReady : false, // Callback for when the plugin is initialised
onChangeStart: false, // Callback for the start of the slide change animation
onChangeEnd : false, // Callback for the end of the slide change animation
onComplete : false, // Callback for the end of the slides being reached
onInteraction: false // Callback for when a user interacts with any controls
});
This defines whether or not previous/next arrow controls should be used. If passed as false, no arrow controls will be generated or used.
If passed as true, the arrow controls will be generated and added to the DOM inside the target element as the following:
<button class="arrow previous">Previous</button>
<button class="arrow next">Next</button>
If you wish to define your own HTML for the arrow controls, you can pass jQuery selectors for the arrow controls. These can either be passed as an array with two elements (the first is assumed as the previous control, and the second is assumed as the next control):
$('.gallery').carousel({
arrows: [$('.gallery .myPrevButton'), $('.gallery .myNextButton')]
});
Or as an object with named properties of next and either prev or previous. Both of the following are valid:
$('.gallery').carousel({
arrows: {
prev: $('.gallery .myPrevButton'),
next: $('.gallery .myNextButton')
}
});
$('.gallery').carousel({
arrows: {
previous: $('.gallery .myPrevButton'),
next : $('.gallery .myNextButton')
}
});
Note that the button elements can be any element, they don't have to be <button>'s.
The arrows option defaults to false.
This defines whether or not position indicators should be created or not. If passed as false, no indicators will be generated.
If passed as true, the indicators will be generated and inserted after the carousel wrapping element (this is automatically generated for every carousel).
It is possible to override the destination for the generated indicators by passing a jQuery object for this setting. For example:
$('.gallery').carousel({indicators: $('.my-indicators')});
The indicators are always generated as an ordered list. The HTML for indicators for a carousel with three slides would look like this:
<ol class="indicators">
<li class="active"></li>
<li></li>
<li></li>
</ol>
The indicators option defaults to false.
This defines the animation to use when moving between slides. Currently, the only supported value is slide. Any other value will cause an error to be thrown.
The animation option defaults to slide.
This defines the speed in milliseconds for the transition between slides.
The speed option defaults to 100.
This defines the delay in milliseconds between automatically transitioning between slides. If passed as false, the carousel will not automatically transition between slides.
The interval option defaults to false.
This defines whether or not the carousel is flexible. If passed as true, an event listener is set up for resize and orientationchange on window to check when the width of the carousel wrapper changes and resize the carousel itself appropriately.
This is very helpful for fluid width websites or when using media queries and device orientation.
The flexible option defaults to true.
The following options are callbacks and can be passed as functions when the plugin is instantiated.
There are no callbacks defined by default.
The first and only argument for all callbacks is passed as the jQuery selector for the appropriate carousel(s).
This callback is fired once the plugin has finished initialising and is ready to be used.
This callback is fired when the transition for changing slide starts.
This callback is fired when the transition for changing slides finishes.
This callback fires when the transition for changing to the last slide finishes. This can be fired multiple times: whenever the last slide is reached.
This callback is fired whenever any of the controls (arrows or indicators) are clicked.
It is helpful for stopping the automatic cycling of slides when the user takes control for usability reasons.
The following public methods are available:
This method will detect if the width of the carousel's wrapper has changed, and re-sets the widths if it has.
function whenLayoutChanges() {
$('.mycarousel').carousel('detectWidthChange');
}
Sets the width of the carousel. The width parameter must be an integer of the desired width in pixels.
function whenCarouselZoom() {
$('.mycarousel').carousel('setWidth', 1280);
}
Moves to the desired slide. index should be the index of the slide to move to, where 0 is the first slide.
This is a shortcut method for goTo(0). It takes you to the first slide.
function resetWebsite() {
$('.mycarousel').carousel('goToStart');
}
This is a shortcut method to go to the last slide.
function fastForwardMyCarousel() {
$('.mycarousel').carousel('goToEnd');
}
This is a shortcut method to go to the next slide. If the active slide is the last slide, an error is raised.
$('.my-custom-next-button').click(function() {
$('.mycarousel').carousel('goToNext');
});
This is a shortcut method to go to the previous slide. If the active slide is the first slide, an error is raised.
$('.my-custom-previous-button').click(function() {
$('.mycarousel').carousel('goToPrevious');
});
This method is essentially the same as goToNext, however if the active slide is the last slide, the active slide becomes the first slide rather than an error being raised.
$('.click-me-willy-nilly').click(function() {
$('.mycarousel').carousel('cycle');
});
Starts the automatic transitioning between slides. If the interval option was passed as either false or not a valid number, an error is raised.
function startPageAnimating() {
$('.mycarousel').carousel('start');
}
Stops the automatic transitioning between slides if it is currently running. Once this is called, it is possible to start up the same interval using the start method.
function freezePage() {
$('.mycarousel').carousel('stop');
}
This plugin adds some helpful classes to various elements:
disabledis added to arrows when appropriate.- This is added to the next arrow when the active slide is the last slide.
- This is added to the previous arrow when the active slide is the first slide
activeis added to the current slide's indicator when the slide transition starts.
This repository uses the HubFlow workflow (see "A successful Git branching model") and Semantic Versioning. Please follow these guidelines and use these tools when contributing to this repository.