image-viewer.js
v1.9.12
Published
jQuery image viewer
Downloads
54
Maintainers
Readme
image-viewer.js
Basic usage
This image viewer is a jQuery plugin. It is activated on an element like so:
var $viewer = $('#id');
$viewer.imageViewer({
image: 'path/to/image.jpg';
});
It takes various options, but at minimum you need image
with a string or images
with an array. You can also set
the options as data attributes instead of passing them in.
Full option list
controls
- Type:
object
- Contains the controls (their names and icons) that will display on the image viewer. Leave out controls to exclude them from displaying.
- Default: See below
controls.zoomToActualSize.icon
- Type:
string
- Class for the icon to use for the zoom to actual size button.
- Default:
fa fa-expand
controls.zoomToActualSize.name
- Type:
string
- Name to use for the zoom to actual size button.
- Default:
Actual Size
controls.fitToContainer.icon
- Type:
string
- Class for the icon to use for the fit to container button.
- Default:
fa fa-compress
controls.fitToContainer.name
- Type:
string
- Name to use for the fit to container button
- Default:
Fit
controls.pan.iconUp
- Type:
string
- Class for the icon to use for the pan up button.
- Default:
fa fa-angle-up
controls.pan.iconDown
- Type:
string
- Class for the icon to use for the pan down button.
- Default:
fa fa-angle-down
controls.pan.iconLeft
- Type:
string
- Class for the icon to use for the pan left button.
- Default:
fa fa-angle-left
controls.pan.iconRight
- Type:
string
- Class for the icon to use for the pan right button.
- Default:
fa fa-angle-right
controls.zoomFactor.name
- Type:
string
- Name to use for the zoom factor text box.
- Default:
Zoom Factor
controls.zoomIn.icon
- Type:
string
- Class for the icon to use for the zoom in button.
- Default:
fa fa-search-plus
controls.zoomIn.name
- Type:
string
- Name to use for the zoom in button.
- Default:
Zoom In
controls.zoomIn.repeat
- Type:
boolean
- Whether to keep zooming in as long as the user holds down the button.
- Default:
true
controls.zoomOut.icon
- Type:
string
- Class for the icon to use for the zoom out button.
- Default:
fa fa-search-minus
controls.zoomOut.name
- Type:
string
- Name to use for the zoom out button.
- Default:
Zoom Out
controls.zoomOut.repeat
- Type:
boolean
- Whether to keep zooming out as long as the user holds down the button.
- Default:
true
controls.rotateFactor.name
- Type:
string
- Name to use for the rotate factor text box.
- Default:
Rotate Factor
controls.rotateLeft.icon
- Type:
string
- Class for the icon to use for the rotate left button.
- Default:
fa fa-rotate-left
controls.rotateLeft.name
- Type:
string
- Name to use for the rotate left button.
- Default:
Rotate Left
controls.rotateLeft.repeat
- Type:
boolean
- Whether to keep rotating left as long as the user holds down the button.
- Default:
undefined
controls.rotateRight.icon
- Type:
string
- Class for the icon to use for the rotate right button.
- Default:
fa fa-rotate-right
controls.rotateRight.name
- Type:
string
- Name to use for the rotate right button.
- Default:
Rotate Right
controls.rotateRight.repeat
- Type:
boolean
- Whether to keep rotating right as long as the user holds down the button.
- Default:
undefined
controls.focus.icon
- Type:
string
- Class for the icon to use for the focus button.
- Default:
fa fa-search
controls.focus.onName
- Type:
string
- Name to use for the focus button when it's on.
- Default:
Focus: On
controls.focus.offName
- Type:
string
- Name to use for the focus button when it's off.
- Default:
Focus: Off
showControls
- Type:
boolean
- Whether to start with the controls hidden.
- Default:
true
images
- Type:
Array.<string>,
- Images to load into the viewer.
- Default:
[]
image
- Type:
string
- The image to load into the viewer. This is used only if
images
is not included. - Default:
undefined
currentImage
- Type:
number
- Index of the current image. Setting this allows you to decide which image first displays.
- Default:
0
spinnerClass
- Type:
string
- Class to use for the spinner icon.
- Default:
fa fa-spin fa-spinner
missingMessage
- Type:
string
- What to display if the image does not exist.
- Default:
Image does not exist!
noneMessage
- Type:
string
- What to display if no images are passed in.
- Default:
No images to display
focusBoxes
- Type:
Array.<object>
- Focus boxes to display after the image loads. The coordinates should be in relation to the image, not the canvas.
- Default:
[]
focusCloseIcon
- Type:
string
- Close icon for focus boxes.
- Default:
fa fa-close
focusMinSize
- Type:
number
- Minimum allowed size of a focus box (only applies while dragging).
- Default:
20
focusOpacity
- Type:
number
- Opacity of the black overlay when focusing.
- Default:
0.5
absoluteFocusBoxes
- Type:
boolean
- Suppose you had a focus box at (10, 10). If this is set to true, the focus box will always be at (10,10) in relation to the image no matter how it is rotated.
- Default: false
allowFocusDrag
- Type:
boolean
- Whether you can drag and create focus boxes.
- Default: `true``
focusMax
- Type:
number
- Maximum number of focus boxes you can have.
- Default:
1
panFactor
- Type:
number
- How much to pan with each step.
- Default:
10
rotationFactor
- Type:
number
- How much to rotate with each step.
- Valid options are
1
through359
- Default:
90
zoomFactor
- Type:
number
- How much to zoom with each step.
- Valid values are
0.1
through1
capMaximumZoom
- Type:
boolean
- Whether to cap the maximum zoom to the image size.
- Default:
true
capMinimumZoom
- Type:
boolean
- Whether to cap the minimum zoom to the canvas size.
- Default:
true
loadZoom
- Type:
number
- At what size the image should load. This is a percentage of the original image size.
- Valid values are
0
through1
- Default:
0
loadPosition
- Type:
string
- Where to put the image on load. Only takes effect if the image does not fit on the canvas.
- Valid values are
top
andcenter
rotations
- Type:
Array.<number>
- Holds rotation values for images.
- Default:
[]
loadRotation
- Type:
number
- What rotation the images should load with. This is used only if
rotations
is not included. - Default:
undefined
keyCodes
- Type:
Object
- Contains key codes for controlling the image viewer via the keyboard. When in a text field, you must also press CTRL or ALT for these keys to work (so that they don't override your typing). Leave out controls to disable them.
- Default: See below
keycodes.closeFocusBox
- Type:
Array.<number>
- The escape key closes focus boxes by default.
- Default:
[27]
keycodes.panLeft
- Type:
Array.<number>
- The left arrow key pans left by default.
- Default:
[37]
keycodes.panUp
- Type:
Array.<number>
- The up arrow key pans up by default.
- Default:
[38]
keycodes.panRight
- Type:
Array.<number>
- The right arrow key pans right by default.
- Default:
[39]
keycodes.panDown
- Type:
Array.<number>
- The down arrow key pans down by default.
- Default:
[40]
keycodes.zoomOut
- Type:
Array.<number)
- The minus key zooms out by default. Firefox uses 173 for the minus key.
- Default:
[189, 173]
keycodes.zoomIn
- Type:
Array.<number>
- The equals/plus key zooms in by default. Firefox uses 61 for the equals/plus key.
- Default:
[187, 61]
keycodes.rotateLeft
- Type:
Array.<number>
- The
l
key rotates left by default. - Default:
[76]
keycodes.rotateRight
- Type:
Array.<number>
- The
r
key rotates right by default. - Default:
[82]
keycodes.zoomToActualSize
- Type:
Array.<number>
- The
a
key zooms to actual size by default. - Default:
[65]
keycodes.fitToContainer
- Type:
Array.<number>
- The
f
key fits to container by default. - Default:
[70]
keycodes.previousImage
- Type:
Array.<number>
- The
q
key goes to the previous image by default. - Default:
[81]
keycodes.nextImage
- Type:
Array.<number>
- The
w
key goes to the nextimage by default. - Default:
[87]
keycodes.toggleControlBar
- Type:
Array.<number>
- The
h
key shows and hides the control bar by default. - Default:
[72]
preload
- Type:
boolean
- Whether to preload images.
- Default:
false
Events
The plugin emits events after the image or a focus box changes. For example:
$viewer.on('viewer:rotated', function (event, data) {
// This will run every time the image has finished rotating.
// We can use this to update the details in the database.
});
Events are "debounced", so they won't fire until the user has finished the action.
Some events are passed data
(see below). This contains the image properties such as width
, height
, left
, top
, and
rotation
.
Full event list
viewer:ready
- Parameter: event
- Triggered when the image viewer has finished loading.
viewer:zoomed
- Parameter: event
- Parameter: imageData : Contains the image's position, size, and rotation.
- Triggered when the image zooms in or out.
viewer:moved
- Parameter: event
- Parameter: imageData : Contains the image's position, size, and rotation.
- Triggered when the image pans in any direction.
viewer:rotated
- Parameter: event
- Parameter: imageData : Contains the image's position, size, and rotation.
- Triggered when the image rotates left or right.
viewer:resized
- Parameter: event
- Triggered when the viewer is resized due to the window resizing.
viewer:changed
- Parameter: event
- Parameter: currentImage : The index of the current image in the array of images.
- Triggered when the image changes.
focus:moved
- Parameter: event
- Parameter: focusData : The focus's position and size.
- Triggered when a focus box is moved.
focus:created
- Parameter: event
- Parameter: focusData : The focus's position and size.
- Triggered when a focus box is created.
focus:deleted
- Parameter: event
- Triggered when a focus box is deleted.
controls:toggled
- Parameter: event
- Parameter: showing : Whether the control bar is now showing or hiding.
- Triggered when the control bar is toggled.
Calling methods
Any methods in the plugin can be called like so:
$viewer.imageViewer('methodName', 'argument1', 'argument2');
You can also call reInit
with new or changed options and it will intelligently do what it needs to do. Or grab the
plugin instance from $.data
and run with that.
The most useful methods are probably:
jumpToImage(newImage)
- Will switch to the image you specify.
addNewFocusBox(left, top, width, height, center)
- Creates a new focus box at the coordinates you specify.
center
specifies whether to move the viewer to center on the new focus box.
closeFocusBox(index)
- Close the focus box you specify (leave empty to close the current focus box).