Main syntax:
$("selector").xzoom({options});
For example, initialize with 1 class name:
$(".xzoom").xzoom();
In this case xZoom will take first image of the class ".xzoom" as main source image to provide zoom functionality on it. Other images with the same class will be used as thumbnails.
Initialize with 2 and more class names:
$(".xzoom, .xzoom-gallery").xzoom();
In this case xZoom will take only first image of the class ".xzoom" as main source image, then will ignore all other images of the class ".xzoom", and starting from second class ".xzoom-gallery" it will use all of the images as thumbnails.
It is possible also to use the ID for the main source image in initialization, like:
$("#main_image, .xzoom-gallery").xzoom();
The HTML structure of all zoom images, must be the next:
<!-- Main image, on which xzoom will be applied -->
<img class="xzoom" id="main_image" src="path/to/preview/1.jpg" xoriginal="path/to/original/1.jpg">
<!-- Thumbnails -->
<a href="path/to/original/2.jpg">
<img class="xzoom-gallery" width="80" src="path/to/thumbs/2.jpg" xpreview="path/to/preview/2.jpg">
</a>
<a href="path/to/original/3.jpg">
<img class="xzoom-gallery" width="80" src="path/to/preview/3.jpg">
</a>
Note: all thumbnails must be wrapped by 'a' tag, where 'href' attribute contains the path to original big image.
Here is list of all possible options and their description:
Property | Default | Description |
---|---|---|
position | right | Position of zoom output window, one of the next properties is available "top", "left", "right", "bottom", "inside", "lens", "#ID". |
mposition | inside | Position of zoom output window in adaptive mode (i.e. for mobile devices) available properties: "inside", "fullscreen". |
rootOutput | true | In the HTML structure, this option gives an ability to output xzoom element, to the end of the document body or relative to the parent element of main source image. |
Xoffset | 0 | Zoom output window horizontal offset in pixels from output base position. |
Yoffset | 0 | Zoom output window vertical offset in pixels from output base position. |
fadeIn | true | Fade in effect, when zoom is opening. |
fadeTrans | true | Fade transition effect, when switching images by clicking on thumbnails. |
fadeOut | false | Fade out effect, when zoom is closing. |
smoothZoomMove | 3 | Smooth move effect of the big zoomed image in the zoom output window. The higher value will make movement smoother. |
smoothLensMove | 1 | Smooth move effect of lens. |
smoothScale | 6 | Smooth move effect of scale. |
defaultScale | 0 | You can setup default scale value of zoom on opening, from -1 to 1. Where -1 means -100%, and 1 means 100% of lens scale. |
scroll | true | Scale on mouse scroll. |
tint | false | Tint color. Color must be provided in format like "#color". We are not recommend you to use named css colors. |
tintOpacity | 0.5 | Tint opacity from 0 to 1. |
lens | false | Lens color. Color must be provided in format like "#color". We are not recommend you to use named css colors. |
lensOpacity | 0.5 | Lens opacity from 0 to 1. |
lensShape | box | Lens shape "box" or "circle". |
lensCollision | true | Lens will collide and not go out of main image borders. This option is always false for position "lens". |
lensReverse | false | When selected position "inside" and this option is set to true, the lens direction of moving will be reversed. |
zoomWidth | auto | Custom width of zoom window in pixels. |
zoomHeight | auto | Custom height of zoom window in pixels. |
sourceClass | xzoom-source | Class name for source "div" container. |
loadingClass | xzoom-loading | Class name for loading "div" container that appear before zoom opens, when image is still loading. |
lensClass | xzoom-lens | Class name for lens "div". |
zoomClass | xzoom-preview | Class name for zoom window(div). |
activeClass | xactive | Class name that will be added to active thumbnail image. |
hover | false | With this option you can make a selection action on thumbnail by hover mouse point on it. |
adaptive | true | Adaptive functionality. |
adaptiveReverse | false | Same as lensReverse, but only available when adaptive is true. |
title | false | Output title/caption of the image, in the zoom output window. |
titleClass | xzoom-caption | Class name for caption "div" container. |
bg | false | Zoom image output as background, works only when position is set to "lens". |
$(".xzoom").xzoom({option1: value, option2: value, ...});
For the main source image tag:
xoriginal
- the path to the big image, that will be used as zoomed image in zoom.
xpreview
- optional, but when it is set up, this attribute used as the medium preview image, while the src attribute in this case will be used as the small thumbnail image. If this attribute is not set up, then src attribute will be used as the medium preview image.
xtitle
- text string that will be used as caption and will be shown in zoom output window inside "div" container with titleClass. If this attribute is not used then xZoom will use regular title attribute of the image.
Getting an instance:
var instance = $("selector").xzoom({options});
$("selector").xzoom({options});
var instance = $("selector").data('xzoom');
After you got an instance, you are able to use API functions.
List of available methods:
xappend(jQuery_object)
- this function can add new thumbnail to current xZoom instance. It will take as parameter 1, object that must be an image and passed as jQuery object.
gallery()
- this function can be used for integration with gallery plugins, like "FancyBox" or "Magnific Popup", it returns an object with the next properties:
index
- current selected thumbnail. Starting from 0.
ogallery
- array of paths to original big images.
cgallery
- array of paths to original big images. Order begins from current index.
//Example: Integration with FancyBox plugin
$('#main_image').bind('click', function() {
var xzoom = $(this).data('xzoom');
xzoom.closezoom();
$.fancybox.open(xzoom.gallery().cgallery, {padding: 0, helpers: {overlay: {locked: false}}});
event.preventDefault();
});
//Example: Integration with "Magnific Popup" plugin
$('#main_image').bind('click', function() {
var xzoom = $(this).data('xzoom');
xzoom.closezoom();
var gallery = xzoom.gallery().cgallery;
var i, images = new Array();
for (i in gallery) {
images[i] = {src: gallery[i]};
}
$.magnificPopup.open({items: images, type:'image', gallery: {enabled: true}});
event.preventDefault();
});
You are able to rewrite event functions that xzoom uses on some specific steps of working, to have more deep control and expand functionality as you want.
instance.eventopen(element)
Function that is called on initialization step, that is binding an event "mouseenter" to the passed jQuery object "element" which is originnaly a main source image. And giving a function that need to be called when event will be triggered "instance.openzoom".
//Example
instance.eventopen = function(element) {
element.bind('mouseenter', instance.openzoom);
}
Note: usually there is no need to change this function at all, but it is just present as optional feature. Because you just can use main source image via jQuery to bind to it any event and instance function "instance.openzoom" to open xZoom when event fired.
instance.eventleave(element)
Function that is called on the step when it is needed to bind an event to the element on which the leaving will be tracked.
//Example
instance.eventleave = function(element) {
element.bind('mouseleave', instance.closezoom);
}
instance.eventmove(element)
Function that is called on the step when it is needed to bind an event to the element on which the moving will be tracked.
//Example
instance.eventmove = function(element) {
element.bind('mousemove', instance.movezoom);
}
instance.eventscroll(element)
Function that is called on the step when it is needed to bind an event to the element on which the scrolling for scale will be tracked.
//Example
instance.eventscroll = function(element) {
element.bind('mousewheel DOMMouseScroll', instance.xscroll);
}
instance.eventclick(element)
Function that is called on the step when it is needed to bind an event to the element on which the click will be tracked.
//Example
instance.eventclick = function(element) {
element.bind('click', function(event) {
$('#main_image').trigger('click');
});
}
instance.openzoom(event)
Function to open zoom, uses event.pageX and event.pageY as start location of lens.
instance.closezoom()
Has no parameters, and simply closing the zoom.
instance.movezoom(event)
This function also uses event.pageX and event.pageY to be able to provide movement of lens on the zoom.
instance.xscroll(event)
This function is adapted for "mousewheel", "DOMMouseScroll" events and tested, and works fine on all major browsers. But if you are using some custom events where you will call this function directly then you can use event.xdelta as delta with value 0 or 1 to tell the direction of scaling by 5% from each call, or event.xscale for exact scale with value from -1 to 1 (which means -100% to 100%) to set up exact scale of the zoom as you need.
instance.eventunbind()
Function that will delete original instance.event* functions by replacing them with blank functions and unbind default events on objects. It can help you to clear default mouse binding events that xzoom already setup.
instance.eventdefault()
Function that will restore original instance.event* functions.
.xzoom-source img, .xzoom-preview img, .xzoom-lens img {
display: block;
max-width: none;
max-height: none;
-webkit-transition: none;
-moz-transition: none;
-o-transition: none;
transition: none;
}
Also for this case we created an option rootOutput
, so you can take a control where inside html you want xZoom elements to be output. To the end of body
tag or relative to the parent of main source image.
All new features and last updated docs you can find here: github.com/payalord/xZoom