ZoomZu - jQuery Gallery & Slideshow Plugin

Documentation

1. About

ZoomZu is a vertical style gallery & slideshow plugin. With the "Lazy Loading" feature it can automatically load new gallery items as you scroll down the page.

Every item in gallery can have fullscreen slideshow that is activated when you click thumbnail or title. With the "sliderEffect" option you can switch among seven different animation effects to change slides. Another useful option is "sliderImageScale" that allows you to select how images are scaled inside slider viewport - whether they fit or cover the entire area.

ZoomZu is mobile optimized, and along with smooth CSS3 transitions it creates great user experience on different touch screens and mobile devices.

Other features that you can find in this plugin include: navigation, pagination, autoplay, touch-swipe, image preloading, double click/tap zoom, close-on-scroll option, etc.

2. Installation

ZoomZu requires jQuery library, so please make sure that your site loads it. Otherwise you can copy next two files from plugin ZIP to the /js folder under your site

/js/jquery-1.12.0.min.js /js/jquery.easing.1.3.js

and then link them in head section of index.html, like so

<script type="text/javascript" src="js/jquery-1.12.0.min.js"></script> <script type="text/javascript" src="js/jquery.easing.1.3.js"></script>

Now, to install ZoomZu please copy next files/folders from plugin ZIP to the corresponding locations under your site

/blank.gif /js/jquery.zoomzu.min.js /css/zoomzu.css /images/zoomzu/

When it's done, you should link plugin JS and CSS files in head of index.html file

<link type="text/css" rel="stylesheet" href="css/zoomzu.css"> <script type="text/javascript" src="js/jquery.zoomzu.min.js"></script>

Next step is to add HTML markup. Here is how it should look like

<ul id="my-gallery" class="zoomzu">
	
	<!-- item -->
    <li class="zz-item">
    
    	<!-- item thumb -->
        <div class="zz-thumb">
            <a href="#"><img src="blank.gif" data-src="pictures/1.jpg" alt="Thumb" />
            </a>
            <div class="zz-caption"> <a href="#">Title</a> <em>by John Doe</em> </div>
        </div>
        
        <!-- item slider -->
        <div class="zz-slider">
            <ul>
                <li><img src="blank.gif" data-src="pictures/slider/1.jpg" alt="Some caption">
                </li>
                <li><img src="blank.gif" data-src="pictures/slider/2.jpg" alt="">
                </li>
                <li><img src="blank.gif" data-src="pictures/slider/3.jpg" alt="Another caption">
                </li>
                <li><img src="blank.gif" data-src="pictures/slider/4.jpg" alt="">
                </li>
            </ul>
        </div>
        
    </li>
    <!-- end item -->
        
    <!-- item -->
    <li> ... </li>
    <!-- end item -->
</ul>

This is basically a UL list with multiple items. Every item contains two DIVs - "zz-thumb" and "zz-slider". Note that every <img/> has "src" attribute set to /blank.gif, while it's "data-src" is set to actual image. It was made so that plugin can dynamically preload images when user scrolls to them or when slideshow has been opened.

Every image in slideshow can have a caption. To set caption please add non empty "alt" attribute to the <img/> inside of "zz-slider" UL list.

Ok. When markup is ready, it's time to init plugin. To do this in head section of your index.html add this JS code

<script type="text/javascript">
$(document).ready(function(){ 
	$('#my-gallery').zoomzu({
		sliderEffect: 'slide', 
		sliderDuration: 300 
	}); 
}); </script>

Other plugin options you can find in next section.

3. Options

Here is a complete list with plugin options and callbacks

// default options
var defaults = $.extend({
	css3: true,						// use CSS3 transitions
	lazyLoading: true,				// enable lazy loading for gallery images
	lazyLoadAfter: 2,				// show this number of gallery images when page loads
	lazyLoadAmount: 2,				// number of gallery images to "lazy load" when page is scrolled
	closeOnScroll: true,			// close slider when page is scrolled
	scrollThreshold: 100,			// threshold of page scroll that will close slider, px
	sliderOpen: 300,				// slider open duration, ms
	sliderClose: 300,				// slider close duration, ms
	sliderStartSlide: false,		// reset slider to the specified slide (index) on start, or false
	sliderDuration: 500,			// slider effect duration, ms
	sliderEasing: 'swing',			// slider effect easing
	sliderCarousel: false,			// enable carousel mode
	sliderEffect: 'zoom',			// slider effect name or object, e.g.
									// 'fade', 'crossfade', 'rotate', 
									// 'slide' / {slide:50}, 'zoom' / {zoom:0.1}, 
									// 'cube' / {cube: 45} or 'sphere' / {sphere: 45}
	sliderImageScale: 'fit',		// image scale mode for slider: 'fit' or 'cover'
	sliderZoom: true,				// whether to zoom slide on double tap or click
	sliderZoomLevel: 2,				// slide zoom level, e.g. 1.3 or 4
	navigation: true,				// show prev/next controls
	pagination: true,				// show pagination
	keyboard: true,					// use left/right and esc keys to control slider
	autoPlay: false,				// enable autoplay
	autoPlayDelay: 2000,			// autoplay delay, ms
	showNumber: true,				// display slide number indicator
	swipe: true,					// enable touch swipe
	swipeDelay: 200,				// delay with which slides will change during continuous swipe, ms
	sliderLink: '.zz-thumb a',		// elements inside gallery item that open slider viewport
	onSliderOpen: function(){},		// slider open callback ("this" ref to slider DOM)
	onSliderClose: function(){},	// slider close callback ("this" ref to slider DOM)
	onSlidingStart: function(){},	// sliding start callback ("this" ref to slider DOM)
	onSlidingEnd: function(){}		// sliding end callback ("this" ref to slider DOM)
}, options);

ZoomZu provides few callback functions as well. Inside of these callbacks "this" keyword refers to active slider DOM element. For example you can use onSlidingEnd() callback to start some animation right after sliding transition ends.

4. API

Plugin provides a set of API methods to control plugin from external code

openSlider(index) - open slider for gallery item by specifying item index (zero-based)
closeSlider() - close slider that is open at the moment
isSliderOpen() - check if slider is open
startAutoplay() - start autoplay for active slider
stopAutoplay() - stop autoplay
getSliderSlides() - get items for active slider or null if slider is not open
getActiveSlide() - get active item for slider
moveNext() - move to the next slide
movePrev() - move to the previous slide
moveTo(index) - move to the slide by providing its index (zero-based index)

There is basically two ways to execute these API methods. The first one is to retrieve API object and call its methods, like so

var api = $('#my-gallery').data('zoomzu'); 
api.openSlider(0);

Another way is to send custom "zoomzu" event with params as array using $.trigger() function

$('#my-gallery').trigger('zoomzu', ['openSlider', 0]);

When executing methods that don't require arguments, you can call $.trigger like so

$('#my-gallery').trigger('zoomzu', 'closeSlider');

5. Classes

ZoomZu assigns some classes dynamically at certain moments. This can be used to start CSS3 animation or hide/show elements when some action is taking place.

On the figure below you can see the classes (at the right of an arrow) that are dynamically assigned to elements at the left

.zoomzu → zz-lazy-loading \-- .zz-item → zz-preloading, zz-slider-open \---- .zz-slider → zz-preloading, zz-slider-preloaded, zz-is-sliding, zz-playing, zz-effect-/name/

Thanks for reading!