jQuery ImageHandler2in1 plugin


In this chapter I want to introduce my jQuery plugin ImageHandler2in1 to you. Actually, I haven't checked yet if there is already a similar plugin. At least there are plugins that fulfill the single tasks that the present plugin handles in combination:

It's a widespread problem that you may have images on your webpage that have widths that exceed the widths of their parents' boxes—especially when they were posted by users of your website, so that you won't have any direct influence on how they are scaled. To prevent these images from disturbing the appearance of your overall layout you may have defined the behavior of the parents' boxes with a certain CSS style, for instance by determining the overflow attribute as 'hidden'. On the one hand this procedure leads to the result that your layout won't be disturbed, on the other hand the images may be truncated which is also an undesired effect.

To deal with such problems I usually use the aeImageResize jQuery plugin developed by Adeel Ejaz that is a nice and reliable method. However, once scaled down to a reduced size you can not display the images with their original extensions using this plugin alone.

However, this can be compensated by the use of an additional jQuery plugin, for instance the very famous and awesome slimbox2 plugin provided by Christoph Beyls. In my own webprojects I often use these two plugins in combination and that works very fine. Anyway, I came to the conclusion that these two tasks should be combined into a single plugin and that's what the present plugin is about:



Description of what the plugin does


The ImageHandler2in1 will scale your images to a pre-defined width and additionally allows the user to display the images in their original sizes. You simply have to click the image to open it in a box that is smoothly fading in and floating in front of your page (another click on the image brings you back to the former state). The title attribute of the image element will be used for the caption. When the box appears in the browser window the rest of the content will be entirely covered with a transparent layer and the box itself is centered along the x-axis of the window.

This treatment will be applied to all image elements within a certain container element, no matter what child level the image element has within that parent container. In case you only want to apply this treatment to single images you should wrap SPAN elements around them and give them a certain class name that will then be used as the selector name for the function call with jQuery (see below).

Furthermore, if you only want to use the resize function of the plugin without offering the possibility to enlarge the images, you simply have to set the option "enlarge" to "false" (see below).



The implementation of the ImageHandler2in1 jQuery plugin


If you want to use this plugin for your own web project you first have to download the ImageHandler2in1.js file and store it in a folder. Then you have to embed that file in your HTML sheet using script tags (see below). The function ImageHandler2in1({options)} then must be linked to a certain parent element of your HTML structure that will contain all image elements to which the function shall be applied. In the example this element is a div-container with the id “main” which is used as a selector within the jQuery call.


Note: Of course one first has to embed the jQuery framework beforehand so the plugin code can be interpreted. For the ImageHandler2in1 plugin you will need the 1.7.1 or higher version!



<script type='text/javascript' src='js/ImageHandler2in1.js'></script>
<script type='text/javascript'>


     	$(document).ready(function() {



When you call the ImageHandler2in1 function you will have a number of possibilities to modify the appearance of the box containing the enlarged image. The respective attributes responsible for these effects can simply be added to the object literal. The following attributes can be used:


Attribute Type Default Description
width integer 200 The maximum width (in pixel) for images that exceed this value
enlarge boolean true When set on 'false' only the scaling method will be applied to the images
fadeIn integer 400 The time (in msec) the fading in of the enlarged images will take
fadeOut integer 300 The time (in msec) the fading out of the image will take
backColor string '#012' The color of the transparent background on which the enlarged imgage is displayed
backOpacity float 0.9 The opacity of that overall background
frameColor string '#FFF' The color of the box in which the enlarged image is presented
captionColor string '#666' The font color of the caption text
captionFont string 'Verdana,Arial' The font family of the caption text
captionSize string '12px' The font size of the caption text
captionWeight string 'normal' The font weight of the caption text
captionOverflow string 'hidden' The way the box will deal with caption text that contains too long strings.


Additional remarks


This is version 1.0 of the ImageHandler2in1 jQuery plugin. Although I successfully tested its functionality with several browsers (IE 6+, the latest versions of Chrome, Opera and Mozilla Firefox) there may still be bugs. So, in case you experience any undesired behavior with that plugin or you have any questions about that plugin in general, feel free to leave a comment on that page!






© 2012 G. Wendt

Write a comment
Name: Note: Your email address will not be displayed on this site nor otherwise published!
Color & Font
Color tool

You have difficulties finding a balanced color combination and appropriate font formats for your website?

Use the tool Color & Font on this website in order to interactively create the color and font properties of your own site. The results of your settings can be easily included as CSS listing in your web project.