PaW Carousel – infinite, responsive, lightweight jQuery plugin

Author: Pictures & Writing / Shaun Morrison

What's new in Version 2?

How to use

Find all files on Github https://github.com/shaunmorrison/PaW-Carousel, or look at the source of this page; alternatively, follow the information below:

Include CSS, jQuery, PaW Carousel plugin and JS call e.g.

<link rel="stylesheet" href="css/pawcarousel.css">
<!--You can use jQuery 2.x as well if you don't want to support older browsers -->
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
<script src="js/pawcarousel.jquery.min.js"></script>
<script>
$(function(){
	$('.paw-carousel').pawCarousel();
	// If you want to add another carousel on the same page
	$('.paw-carousel-2').pawCarousel();
});
</script>

Add the HTML to your page e.g.

<section class="paw-carousel-wrap">
<div class="paw-carousel">
	<div class="paw-carousel-items-wrap">
		<div class="paw-carousel-item">
			<img src="images/x.gif" data-src="assets/media/egs/eg-01.jpg" data-src-2x="assets/media/egs/eg-01@2x.jpg" width="494" height="370" class="paw-carousel-item-media">
			<h3>This is some description text</h3>
		</div>
		<div class="paw-carousel-item">
			<a href="http://picturesandwriting.com" title="A link to Shaun's portolfio site">
				<img src="images/x.gif" data-src="assets/media/egs/eg-02.jpg" data-src-2x="assets/media/egs/eg-02@2x.jpg" width="494" height="370" class="paw-carousel-item-media"">
				<h3>This image has a link</h3>
			</a>
		</div>
		<div class="paw-carousel-item">
			<iframe width="560" height="315" src="//www.youtube.com/embed/aYxni8ohTfU" frameborder="0" allowfullscreen></iframe>
		</div>
	</div>
	<!--Next and previous links. SVGs - change with PNGs if you want browser support -->
	<a href="#" class="paw-carousel-prev"><img src="images/arr-prev.svg" alt="Previous"></a>
	<a href="#" class="paw-carousel-next"><img src="images/arr-next.svg" alt="Next"></a>
	<!--Left and right translucent masks - simply remove if not required-->
	<div class="paw-carousel-mask paw-carousel-mask-l hide-med"></div>
	<div class="paw-carousel-mask paw-carousel-mask-r hide-med"></div>
</div>
<!--Thumbnail navigation-->
<nav id="paw-carousel-thumbs">
	<ul>
		<li class="paw-carousel-nav-item"><img src="assets/media/egs/eg-t-01.jpg"></li>
		<li class="paw-carousel-nav-item"><img src="assets/media/egs/eg-t-02.jpg"></li>
		<li class="paw-carousel-nav-item"><img src="assets/media/egs/eg-t-03.jpg"></li>
	</ul>
</nav>
</section>

Options

Call options the usual way e.g.

$('.paw-carousel').pawCarousel({
	carouselItemCls: 'slide-item',
	animSpeed: 1500,
	alignment: 'left'
});
Option name Option default Options Option description
carouselItemCls 'paw-carousel-item' Any valid class name The class that wraps each carousel item.
carouselItemMediaCls 'paw-carousel-item-media' Any valid class name The class that wraps each carousel item's media e.g. the main image or video.
carouselItemsWrapCls 'paw-carousel-items-wrap' Any valid class name The class of the DIV that contains the carousel items only.
carouselNavItemCls 'paw-carousel-nav-item' Any valid class name The class that wrap each nav/thumbnail item.
nextLinkCls 'paw-carousel-next' Any valid class name The class of the next link.
prevLinkCls 'paw-carousel-prev' Any valid class name The class of the prev link.
activeCls 'active' Any valid class name The class of the active item in the carousel and the thumbnails.
croppedCls 'cropped' Any valid class name The class when an image becomes cropped (when the carousel item is larger than the container).
carouselItemSpace 'css' Either 'css' or a positive integer/number This is the margin-right of each carousel item. If 'css' it will calculate from your CSS, if set as an integer then will write this margin-right value to each item.
animSpeed 800 Any number in milliseconds Animation speed of next/prev + thumbnail nav.
alignment 'center' 'center', 'left', 'right' Aligned the active item to the left, right or center of the carousel.
setsEachSide 1 Any positive integer/number. How many sets get cloned to each side of the original. This give it the 'infinite' look. Probably want to stick with '1' unless you have very few narrow items in your slide show.
carouselHtType 'shortest' 'shortest', 'tallest' or any positive integer/number 'shortest' crops slideshow height to the shortest item (excluding videos).
'tallest' sets the slideshow to the tallest item (excluding videos); an integer/number will set the slideshow to this height (in px).
carouselResizeType 'cropped' 'cropped', 'scaled' 'cropped' at smaller screensizes retains the original item height and crops in the sides of the item – the image is centrally aligned.
'scaled' shows all the image at any screen size; however, this does mean carousels can become short at smaller screen sizes + if you have any wide images.

FAQs

What can I do to support further development of this and other plugins like this?

Well, it would be super for you to tell others about this plugin. If you have found it's saved you some time you may feel inclined to give me a modest amount of cash through PayPal: shaun@picturesandwriting.com

What browsers does this work in?

Older versions of Firefox, Safari and Chrome; as well as IE7+. IE 7 & 8 may have animation/performance issues depending on how many images you have.

Can I have images at different sizes?

The carousel looks best when the images are the same height, but can be any width. The carousel by default will set it's height to the shortest image.

What happens to different width images at narrower screen & mobile sizes?

The images will be cropped in from the sides leaving the centre of the images. If we scaled the images keeping their ratio the carousel tends to becomes comically short. Edit: Added the option to show the full image at all screen sizes is set through the 'carouselResizeType' option (see above).

How to include image height and width dynamically through CMSs?

Any CMS worth it's salt provides a plugin architecture for you. I used the PHP func getimagesize() to get each image's dimensions. Here's a MODX plugin as an example:

<?php
$o = '';
$src = $modx->getOption('src',$scriptProperties, null);
//Doesn't find image if prepended with root slash. So remove if present
if(substr($src , 0, 1 ) === '/'){
	$src = substr($src, 1);
}
//Doesn't want the %20 space replace in src, just plain old spaces
$src = str_replace('%20', ' ', $src);
$imagesize = getimagesize($src);
$width = $imagesize[0];
$height = $imagesize[1];
// I know you're not meant to output HTML, but I don't want to create templates for this
$o = 'width="' . $width . '" height="' . $height . '" ';
return $o;

Why not generate more of the markup through JS?

I may change my mind about it the future, but I like to keep the JS small and lean. I am aware it could help eliminate human error e.g. forgetting to add the inner 'paw-carousel-items-wrap' DIV.

Code Copyright and License

© Copyright 2014 Shaun Morrison. The PaW Carousel code is licensed under the GPL – http://www.gnu.org/licenses/gpl.html license.

Images / Photos Copyright

© 2014 Shaun Morrison. All rights reserved.

The images are under full copyright with no permission to share or distribute in either commercial or non-commercial instances, unless permission by Shaun Morrison is granted. You may use them as examples for the PaW Carousel plugin on Github for Pull Requests.

Future developments

  1. Doesn't yet have an API to add things like 'before' and 'after' events.
  2. I'll largely leave it up to the public via Github to decide where this needs expansions/development.