imgZoom Documentation

Last revised: Sep 30, 2011

Introduction
Basic Usage
Options
Wrap
API Methods

Introduction

ImgZoom is a jQuery plugin that implements a smooth zoom effect on images. It uses vector graphics (SVG or VML) to create a graceful transition between the thumbnail and the full-sized image.

Basic Usage

The standard way of using the plugin is with a number of thumbnail images that link to larger pictures, e.g.:

<a href="puppy.jpg"><img class="thumbnail" src="puppy_small.jpg" alt="Puppy" /></a>
<a href="kitten.jpg"><img class="thumbnail" src="kitten_small.jpg" alt="Kitten" /></a>
<a href="spider.jpg"><img class="thumbnail" src="spider_small.jpg" alt="Spider" /></a>

To enable the zooming functionality for these images, select them with a jQuery selector and call the imgZoom() method:

$(document).ready(function () {
    $('img.thumbnail').imgZoom();
});

The plugin automatically picks up the href attribute of each immediate parent element and uses it as the location of the full-size image.

If your HTML document is structured differently, i.e. the thumbnails are not wrapped in links that point to the larger versions, you can use the src option to explicitly set the location of the full-size image.

Options

The plugin can be initialized with a number of options, passed as an object to the imgZoom() method. The available options are:

Option	Description
`classPrefix`	A string that is prepended to class names assigned to plugin elements (see below for details) default: `"imgzoom"`
`duration`	The duration of the zoom in/zoom out animation (in milliseconds). default: `500`
`fastSwitch`	If set to `true`, switching to the previous/next image happens without the zoom out/zoom in animation. default: `false`
`group`	If you want to have multiple groups of images on the page, and navigate them independently (using the prev/next links), use this option to set a specific name for each group.
`hideThumbnail`	If set to `true`, the thumbnail image turns invisible when animation starts. default: `false`
`instance`	If set to `true`, the `imgZoom()` call returns a reference to an instance of imgZoom bound to the image, allowing you to use its API methods (see below).
`loadingImg`	The URL of the image used as a "loading" icon, displayed on top of the thumbnail when the full-sized image is loading. default: `"css/imgzoom-loading.gif"`
`opacity`	If set to a number between `0` and `1`, the image's opacity is gradually increased starting with the given value and ending with 1, producing a fade-in effect. If set to an array of two numbers, the numbers correspond to the starting and ending opacity. default: `1`
`overlayOpacity`	The opacity of the overlay (visible when showOverlay is `true`). default: `0.75`
`remove`	If set to `true`, the plugin is removed.
`rotate`	If set to `true`, the image does a 360° clockwise rotation while zooming in. If set to a positive integer greater than 1, it defines the number of rotations. If set to a negative integer, the image is rotated counter-clockwise. default: `false`
`showOverlay`	If set to `true`, a semi-transparent black overlay is displayed in the background of the full-size image. default: `false`
`src`	URL of the full-size image, if it's not referenced by the parent's `href` attribute.
`title`	Image title that will be displayed in the wrap. If not specified, the plugin reads it from the `title` attribute of the anchor element containing the image, or the `title` of the image element itself.
`wrap`	A block of HTML code that will be wrapped around the full-size image (see below for details).
`wrapDuration`	The duration of the wrap fade-in animation (in milliseconds). default: `300`

You can call the plugin more than once on the same <img> element with a new set of options, and the new options will override the old ones. For example, if you set a new value for the duration option, the animation speed will be changed. The two exceptions are the src and group options -- these can only be set when the plugin is initialized.

Wrap

After the image is zoomed in to its full size, it gets wrapped in a block of HTML code that displays additional information and user interface elements, like the image's title, navigation buttons for previous and next images, and so on. The plugin provides the default wrap block – if you want to use a different one, you can set it with the wrap option.

There is a number of classes that need to be assigned to wrap block elements to define their roles. For example, if you add the imgzoom-next class to an element, then clicking it will switch to the next image. The table below lists all the classes recognized by the plugin:

Class Name	Description
`imgzoom-wrap`	The root element of the wrap block must have this class.
`imgzoom-container`	The container element that the full-size image will be appended to. One element with this class must be present in the wrap block.
`imgzoom-title`	The contents of this element will be set to the title of the image.
`imgzoom-current`	The contents of this element will be set to the number of the currently displayed image.
`imgzoom-last`	The contents of this element will be set to the number of the last image in the set.
`imgzoom-prev`	Clicking this element will switch to the previous image in the set.
`imgzoom-next`	Clicking this element will switch to the next image in the set.
`imgzoom-close`	Clicking this element will close the currently displayed image.
`imgzoom-width`	Any element with this class will have its width set to the width of the currently displayed image.
`imgzoom-height`	Any element with this class will have its height set to the height of the currently displayed image.
`imgzoom-wrap-first`	Automatically assigned to the element with the `imgzoom-wrap` class if the currently displayed image is the first one.
`imgzoom-wrap-last`	Automatically assigned to the element with the `imgzoom-wrap` class if the currently displayed image is the last one.

The default wrap block has the following structure:

<div class="imgzoom-wrap imgzoom-width">
    <div class="imgzoom-container imgzoom-width imgzoom-height">
        <a href="#" class="imgzoom-prev"><span>Prev</span></a>
        <a href="#" class="imgzoom-next"><span>Next</span></a>
    </div>
    <div class="imgzoom-counter">
        <span class="imgzoom-current" />&nbsp;of&nbsp;
        <span class="imgzoom-last" />
    </div>
    <div class="imgzoom-title" />
    <div class="imgzoom-close">Close</div>
</div>

Since the plugin requires that the wrap block has an element with the imgzoom-wrap class containing one element with the imgzoom-container class, the simplest block that you can use is:

<div class="imgzoom-wrap">
    <div class="imgzoom-container" />
</div>

API Methods

A number of API methods are provided to make it easier to extend the plugin and to integrate it with other web application components.

In order to use these methods, you need an instance of the plugin's object. To get one, call the imgZoom() method with the instance option set to true:

var imgzoom = $('#thumbnail').imgZoom({ instance: true });

You can then use this object to call the public methods. For example, to start a slow (two-second) zoom of the image, you can call the zoomIn() method, passing 2000 as the parameter:

imgzoom.zoomIn(2000);

Note that you should only use the instance after the plugin has been fully initialized, i.e. in the onInit callback function, or anytime after onInit has been triggered.

The following methods are available: