SimpleZoom v.1.0.1
The SimpleZoom jQuery plugin creates a user controlled viewfinder element which is used to designate a region of the target image to be enlarged and then displayed within the plugins designated viewport element. By default the viewport and viewfinder are the same element creating the impression of a magnifying lens. Alternatively, a separate element may be specified as the active viewport.
SimpleZoom offers customization through various options, and automation through a simple API exposed as plugin methods and events.
SimpleZoom: A jQuery Plugin for Magnifying Images (ver.0.2.2)
Description
This post refers to an old version of the SimpleZoom plugin. For the latest version of this plugin check out /blog/tag/simplezoom.
In my inaugural blog post I introduced a jQuery plugin for magnifying images named SimpleZoom. The purpose of this post is to introduce the updated SimpleZoom v.0.2.2 which adds new options and greatly simplifies the invocation process.
The SimpleZoom plugin is intended to be invoked upon an <img> element for which a corresponding higher resolution image resource is available. This higher resolution image, which is provided to the plugin via its URL, then acts as the magnified image. Of course, invocation need not follow this specific pattern. Indeed, the plugin may be invoked upon any DOM element while specifying any image resource desired.
Once initialized, the SimpleZoom plugin creates a user controlled viewfinder widget which is used to designate a portion of the magnified image to be displayed within the plugins viewport widget. By default, the viewport and viewfinder widgets are combined to give the impression of a single "magnifying lens" widget. Alternatively, a separate DOM element may be specified as the plugins active viewport.
Tested for compatibility with jQuery versions 1.9.1, 1.8.2, 1.8.0 and 1.7.2 on most major browsers going back to IE7.
Usage
The SimpleZoom plugin may be invoked in the following manner.
- JavaScript
$(target).simpleZoom(src, options);
Argument | Type | Required? | Description |
---|---|---|---|
target | jQuery Object/Selector or DOM Element | Yes | <img> element or any fixed dimensional element with a set background-image. |
src | String | Yes | Specifies the URL of an existing image resource to be displayed within the plugins viewport widget. This image resource is intended to be a higher resolution version of the target image. |
options | Object or JSON String | No | This optional argument may be used to specify additional parameters in a key-value pair format. A complete listing of valid parameters can be found in the options section below. |
The SimpleZoom plugin may be invoked at any point after the target element appears within the document. Indeed, it is not necessary to wait for any of the associated image resources to load.
Utility Functions
When the SimpleZoom plugin is invoked within a dynamic webpage, situations may arise in which the plugin may need to be "refreshed" in order to continue functioning properly. Such is the case when the target element is dynamically resized or translated. In these instances, the plugin can be notified of possible changes by calling a special refresh utility function. An object with references to the refresh and other utility functions are returned by the SimpleZoom plugin when 'returnUtil' : true is specified as a parameter of the options argument.
- JavaScript
var options = {'returnUtil' : true};
var utilities = $('#small-img').simpleZoom(src, options);
utilities .refresh();
The following table details the existing utility functions.
Function Name | Return Type | Description |
---|---|---|
refresh | Boolean | Corrects the positioning of the viewfinder widget to take into account any changes in the size or position of the target element and returns a boolean value indicating the success or failure of the call. Note that this function is invoked automatically whenever the window is resized. |
destruct | Boolean | Removes the associated plugin instance completely and returns a boolean value to indicate success or failure. |
Styles
Included in the SimpleZoom download package is a stylesheet named simplezoom.css. This is the primary stylesheet for the plugin and must be present in order for it to function. Entries in the stylesheet listed under the 'Customizable CSS' header may be edited and expanded upon. For example, the width, height and border-radius of the combined viewfinder/viewport (magnifying lens) widget may be altered by editing rules for the SZ-zoom CSS class.
The following table details the CSS classes used by the SimpleZoom plugin.
CSS Class | Description |
---|---|
SZ-zoom | Assigned to the combined viewfinder/viewport (magnifying lens) widget. This class entry may be edited to specify custom dimensions for the widget. |
SZ-full | Assigned to the fullscreen image widget when the fullscreen option is enabled. |
SZ-close | Assigned to the "exit" button which appears when in fullscreen image mode. |
SZ-backdrop | Assigned to the backdrop which appears behind the fullscreen image widget. |
SZ-viewfind | Assigned to the standalone viewfinder widget which takes the place of the magnifying lens widget (.SZ-zoom) when a separate viewport is specified as an options parameter . Note that the dimensions of the viewfinder widget determined by the size of the provided viewport element and therefore need not be specified. |
Options
Custom options may be specified for the SimpleZoom plugin as a collection of key-value pairs. Such a collection may be constructed as either a standard Object or a JSON String, and then passed to the SimpleZoom plugin as the secondary argument.
The following table details the valid parameters of the options object.
Parameter | Type | Default | Description |
---|---|---|---|
fadeDuration | Unsigned Long | 250 | Specifies the duration, in milliseconds, of the fade-in and fade-out animations of the viewfinder widget. |
smoothing | Float | 0.35 | Controls how quickly the viewfinder widget moves to a new cursor or touch event position. The value specified should be on the range (0, 1), with larger values corresponding to a faster convergence of the magnifying lens widget to the event position. |
fill | Boolean | true | Determines whether or not the magnified image fills up the viewport when viewing the edges of the target element. |
confine | Boolean | false | When set to true, the viewfinder widget is confined within the boundary of thetarget element. |
viewport | jQuery Object/Selector or DOM Element | null | Sets the plugins active viewport in which the magnified image (i.e., the image resource specified by the src argument) is displayed. When specified, the magnifying lens widget is replaced by a transparent viewfinder widget, which is assigned a CSS class of SZ-viewfind. Note that the dimensions of the viewfinder widget are automatically calculated, and therefore should not be explicitly specified within the simplezoom.css sytlesheet. |
mobile | Boolean | false | Enables mobile touch screen compatibility mode. Note that enabling this option does not actually add any additional functionality for touch screen browsing. |
fullscreen | Boolean | false | When set to true, clicking on the target element will display a fullscreen version of the src image. The image will be sized in order to fit within the window. |
fullPadding | Float | 15 | Specifies the minimum padding, in pixels, between the fullscreen image and the window. |
fullTrans | Unsigned Long | 350 | Specifies the duration, in milliseconds, of the fade-in and fade-out animations for the fullscreen image. |
disableContext | Boolean | false | May be specified to disallow the context menu. |
returnUtil | Boolean | false | When set to true, instead of returning this, the SimpleZoom method will return an object with references to the utility functions refresh and destruct. |
onload | Function | null | Specifies a function to be executed once the image resources associated with a particular invocation of SimpleZoom have been loaded. |
complete | Function | null | Specifies a function to be executed once SimpleZoom has been initialized. |
Demo
Mouseover or tap the image below.
![Winter Lake Digital Painting by Kraig Halfpap](/img/Winter-Lake-SM.jpg)
SimpleZoom: A jQuery Plugin for Magnifying Images
Hello World!
For my inaugural blog post I have written a simple image magnifying jQuery plugin known as SimpleZoom. Invoking SimpleZoom upon a target image element will bind a set of functions to the target's mouseover handler. Triggering a mouseover event upon the target will then cause an animated 'lens' element to appear, displaying some portion of a higher resolution version of the target image. Of course, the image data of the higher resolution version must be specified as arguments of SimpleZoom. Complete invocation methods are detailed below.