Skip to content
can3p edited this page Dec 8, 2014 · 19 revisions

JQuery.iviewer is an jquery ui widget representing image viewer component used to load and view image with ability to zoom image and to drag it with mouse in container.

Note that "jquery UI widget" is important. You need to use jquery ui, not standalone jquery. Widget depends on the jquery.ui.core, jquery.ui.widget and jquery.ui.mouse.

Plugin is expected to work in ie6+, ff2+, google chrome, opera 9+, safari.

Demo: http://test.dpetroff.ru/jquery.iviewer/test/

Usage:

Div container must have position: absolute or position: relative, width and height for plugin to work correctly. For opera container has also to be wrapped in the div with overflow:hidden (see demo page).

Don't forget to look for known issues and to read the Frequently Asked Questions

To run plugin add to your code: $("#yourid").iviewer(options);

Options are:

  • src - url to the image
  • ui_disabled - if true, toolbar buttons will not be added
  • zoom - zoom at plugin start (% or "fit" to fit image in container);
  • zoom_max - max zoom, that can be achieved (%)
  • zoom_min - minimal zoom, that can be achieved (%)
  • zoom_delta - zoom scale step when pressing controls or scrolling with mouse ( default 1.4)
  • zoom_animation - whether the zoom change should be animated ( default true)
  • zoom_base - value in %, which is used in calculation of image scale. Zoom is calculated by formula zoom_base * pow(zoom_delta, n)
  • update_on_resize - boolean; if false plugin doesn't update on window resize and this can be controlled manually (default true)

Callbacks and events:

  • onZoom(ev, new_zoom) - is called on zoom change. new_zoom - new zoom value to be set. If callback returns false, action is aborted;
  • onAfterZoom(ev, new_zoom) - is called on zoom change after animation is complete
  • onStartDrag(ev, point) - is called when user starts to drag image; if false action aborts. Point object contains the coordinated of pointer on the image in the original size without rotation.
  • onDrag(ev, point) - is called during drag action. Point object contains the coordinated of pointer on the image in the original size without rotation.
  • onStopDrag(ev, point) - is called when user stops dragging the image image. Point object contains the coordinated of pointer on the image in the original size without rotation.
  • onMouseMove(ev, point) - is triggered when mouse moves over image. Point object contains the coordinated of pointer on the image in the original size without rotation.
  • onClick(ev, point) - is triggered, when user clicks on the image. Point object contains the coordinated of pointer on the image in the original size without rotation.
  • onStartLoad(ev, src) - is triggered, when widget starts loading new image; src is the url of the new image.
  • onFinishLoad(ev, src) - is triggered, when widget loads the new image; src is the url of the new image.
  • onErrorLoad(ev, src) - is triggered if images has failed to load
  • angle(ev, {angle: angle}) - is triggered, when the image is rotated. angle specified absolute angle at which image is rotated at the moment.

This keyword points to the widget original node, as it is in every event handler in jquery. ev argument is a jQuery.Event object. It was introduced because jQuery UI requires this. Also, all these callbacks are fired as events, so the can be listened with bind. The name of the event is iviewer word + callback name in lowercase. E.g.

$('#viewer').bind('ivieweronfinishload', function(ev, src) { /* handle this */ })

Useful fields and methods:

  • set_zoom(value) - set zoom to value, in %
  • angle(value, abs) - rotate the image. If abs is false or not defined. the rotation will procceed relative to the current image position or set absolutely otherwise. If no parameters were passed the method will return the current image angle.
  • info(prop, dropRotation) - get some info about the image. Valid values for prop are: display_width, display_height - current physical dimensions of the image; orig_width, orig_height - dimensions of the original image; angle - current rotation angle; zoom - current zoom value in %; src - url of current image;
  • fit() - fit image into container
  • center() - center image in container
  • zoom_by(value) - change image scale by value. E.g. +1 multiplies zoom by zoom_delta, -1 - reduces by zoom_delta
  • moveTo(x,y) - move point on the container to the center of container
  • containerToImage(x,y) - converts point coordinates from container to image original
  • imageToContainer(x,y) - converts point coordinates from image original size to container
  • update() - update iviewer object to actual container size
  • loadImage(src) - load different image in viewer. Image will be zoomed to settings.zoom value. Previous image is not cached and zoom value is not remembered

All the methods should be called through jquery ui notation: $('#viewer').iviewer('method', 'arg1', 'arg2')

To handle image object $.ui.iviewer.ImageObject was introduced. Although it's exposed to allow it's modification, try it on your own risk.

All buttons can be completely customized via css.

Look at test example for details.

Known issues:

Setting display:none will result in errors, because browsers set width and height to zero in this case.

Showcase

Clone this wiki locally