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 through 359
• Default: 90

zoomFactor

• Type: number
• How much to zoom with each step.
• Valid values are 0.1 through 1

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 through 1
• 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 and center

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).