Image Handler 3 for v1.3.x

PURPOSE & AIM

Image Handler³ at the heart of it's code is really meant to ease the management of product images (particularly the management of additional product images), and to help improve page performance by optimizing the product images.

Image Handler³ generates product images (based on your image settings) in the Image Handler³ bmz_cache folder. It DOES NOT replace or modify the original images. So it's PERFECTLY safe to use on an existing store.

Image Handler³ enables you to use GD libraries or ImageMagick (if installed on your server) to generate and resize small, medium and large images on the fly on page request. You can simply upload just one image or you can have different sources for medium and large images. Image Handler³ further enables you to watermark your images (overlay a second specific translucent image) and have medium or large images pop up when you move your mouse over a small image (fancy hover).

This contribution includes a powerful admin interface to browse your products just like you would with the Attribute Manager and upload / delete / add additional images without having to do this manually via FTP. Image Handler³ works fine with mass update utilities like EzPopulate.

Features

Improve site performance (faster loading, faster display)
Professional looking images (no stair-effects, smooth edges)
Choose preferred image-types for each image size
Uploading one image automatically creates small, medium and large images on page request
Drops in and out seamlessly. No need to redo your images. All images are kept.
Easy install. One-click-database-upgrade.
Works with mass-update/-upload tools like EzPopulate.
Watermark images to prevent competitors from stealing them.
Fancy image hover functionality lets a larger image pop up whenever you move your mouse above a small image (switchable).
Choose an image background color matching to match you site's color or select a transparent background for your images.
Manage your multiple images for products easily from one page just like you do with attributes in the Products Attribute Manager.

Image Handler³ is meant to ease the work required to setup images for your store. It works WITH default Zen Cart functionality, it does not replace it. There are a couple of threads which explain what Image Handler IS and more importantly what it is NOT. It is suggested that you read everything before you install Image Handler³. Here's some additional FAQs which discuss how product images and the override system work in Zen Cart. It is strongly suggested that if you are NEW to Zen Cart and web development that you read these threads BEFORE you install Image Handler³.

http://www.zen-cart.com/forum/showpost.php?p=978439&postcount=6205

http://www.zen-cart.com/forum/showpost.php?p=989297&postcount=6360

CONFIGURATION

Image Handler³ works out of the box. There’s no need to configure anything if you are ok with the presets. If you want to change the way Image Handler deals with your images go to Configuration > Images.

Image Handler³ creates images (based on your image settings) in the bmz_cache folder. It DOES NOT replace or modify the original images.

Images Configuration page

Go to Configuration > Images page inside your admin interface.

You can tweak everything to your liking. The parameters are pretty self explanatory and feature additional descriptions when you select them. These parameters enable you to tweak settings for

preferred filetypes
compression quality
background color
watermarking
zooming (fancy hover effect)
gravity for watermarking

The parameters to configure image dimensions have been enhanced to not only accept numerical values, but to accept parameters with an appended "!" which implies a force canvas size mode. Images are resized to fit and placed centered inside the fixed canvas instead of resizing the image to just one of the dimensions if it doesn't feature the same aspect ratio as the settings. That sounds too complicated? Trust me, it isn't. Just see for yourself: Configure a nice colored background and test both values with and without the appended "!". Read more about it in the Image Dimensions section (below).

Preferred Filetypes

You can select either .png, .jpg, .gif or no_change for every image size. The original images you upload are kept as they are, but the Image Handler³ generated files (the ones stored in the bmz_cache folders) will be created using the filetype you specify in this setting. Let's repeat this:

The original images you upload are kept as they are, but the Image Handler³ generated files (the ones stored in the bmz_cache folder) will be created using the filetype you specify in this setting.

So here's how this works:
If and you want the large and medium images to be .png files:

You would choose .png for your IH medium images filetype and IH large images filetype settings.
You will leave the small image at the default setting of no_change.
You upload a .jpg file to the product you are updating.

This will result the following:

Image Handler³ will generate .png image files for your large and medium product images regardless as to the format of the original image (in this example the original .jpg will generate a .png file).

Since in this example no_change was selected for your small images, Image Handler³ will generate a small product image in the same file format as the original image uploaded (in this example the image is a .jpg so the small image will be a .jpg -- you get the picture)

The filetype feature provides another means to let Image Handler³ do some of the heavy lifting for you. Instead of having to convert your 1000 .jpg product images to .png's. You can let Image Handler³ do this woirk for you.

Zen Cart will only recognize and display product images that have the exact same file format for each image size. In other words, all small images must be the same filetype, all medium images must be the same filetype, and all large images must be the same filetype.

BUT

Amongst the various images sizes you may have a "mixed bag". For example, you may decide that all small images will be gif's, all medium images will be jpg's, and all large images will be png's. The filetype feature allows you to do just that.

Caution: Image Handler³ will allow you to add any valid image format as an additional image to a product even if the additional image being uploaded is in a different file format than the main product image (For example, the main image is a jpg and the additional images are png). Image Handler³ will display mismatched file extensions in red in the additional images table. This visual indication tells you that you've uploaded an additional image with a different filetype than the main product image. Zen Cart will not "see" this additional image because the file format of the new image does not match that of the main product image.

Notes about filetypes: GIF is ok for small thumbnails and features some basic transparency. JPG doesn't feature transparency but a very good file quality/compression ratio, especially for photographic images. This would be your desired filetype for large and possibly medium sized images. PNG files feature alpha transparency and as much colors as jpg but are generally larger in filesize than both jpg and gif. Internet explorer still has issues displaying alpha transparency, so you better stick with gif, if you need transparency.

Compression Quality

You can specify the quality for rendering to jpg for small, medium and large images. This setting defaults to 85 for all three on a scale from 0 to 100 and is pretty good unless you need either extremely lossless compression or extremely small images. Higher values result in better quality larger files. (and possibly longer loading times for larger files)

Background Color

You can configure the background color for every imagesize by specifying the color's RGB-value separating each color component (red, green and blue) by a colon. The color component's values range from 0 to 255. The following examples should give you an idea how to set the background color.

255:255:255 (white)
255:0:0 (red)
255:200:200 (light red)
0:255:0 (green)
0:0:255 (blue)
255:0:255 (violet)
255:255:0 (yellow

Here's a few sources for obtaining RGB values. Color Schemer even provides a really nice HEX/RGB conversion calculator.

http://rgbchart.com/
http://cloford.com/resources/colours/500col.htm
http://www.colorschemer.com/online.html

If you want to keep the transparency of an uploaded image, you need to set the background color value to transparent.

With gif images you can specify e.g. transparent 255:255:255 instead of just transparent so the half translucent pixels are combined with the specified background color. Pixels with transparency above 90% (this is the default) threshold are rendered full transparent. If you set the latter color to the value of your page's background color, this does enhance visual quality of gifs substantially because of the reduction of stair-effects.

Watermarking

In order for watermarking to work for every image dimension the specific corresponding watermark images have to be present. That means, you have to upload files to the following specific locations:

images/watermark.png
images/medium/watermark_MED.png (or your specified MEDIUM_IMAGE_SUFFIX)
images/large/watermark_LRG.png (or your specified LARGE_IMAGE_SUFFIX)

Image Handler³ includes some demo watermark images for small, medium and large sized images featuring a slightly modified Zen-Cart logo for a quick start. Nothing more to do, switch on watermarks or switch off watermarks in the image settings just as you like. Image Handler³ takes care of generating images accordingly. You can specify where you want the watermark to appear on the image canvas by selecting NorthWest, North, NorthEast, West, Center, East, SoutWest, South and SouthEast for the Watermark Gravity setting.

To use your own watermark, simply create replacement watermark images using the image editing software of your choice. (Your custom watermark files should be PNGs using the same image names as the included sample watermark images) Please note that questions about HOW to create watermarks should NOT be posted on the Image Handler³ support thread. There are TONS of sources on the web which can provide you good guidance on creating watermarks. This link will get you started: How to create watermarks.

Zooming (fancy hover effect)

When selecting this feature for small images, the medium or large image (depending on your admin settings) pops up whenever you move your mouse cursor over the small image.

Note: Zooming in on medium images is not implemented. More on this on the "Misc" tab.

For small image hover to work on the following product listing pages:

All Products
New Products
Featured Products
Special Products

the following settings must match the Small Image Width and Small Image Height settings:

Subcategory Image Width
Subcategory Image Height
Image - Product Listing Width
Image - Product Listing Height
Image - Product New Listing Width
Image - Product New Listing Height
Image - New Products Width
Image - New Products Height
Image - Featured Products Width
Image - Featured Products Height
Image - Product All Listing Width
Image - Product All Listing Height

Additionally, if you want to add the hover effect to category images, the following settings must also match the Small Image Width and Small Image Height settings: Admin> Images > Category Icon Image Width - Product Info Pages

If you selected the medium image as your on-hover image:
You control the size of the medium image via the Product Info dimension.

Note on the Product Info dimension: You can set this to whatever you want, but it cannot be larger than your largest image (Image Handler³ does not enlarge images) nor smaller than your small images (this is considered your MEDIUM image it's dimensions must fall BETWEEN the dimensions you set for you small and large images).

If you selected the large image as your on-hover image:
You control the size of the large image via the Large Image dimension.

Note on the Large Image dimension: You can set it to whatever you want, but if the largest image you upload is smaller than these dimensions Image Handler³ will not enlarge your image (Again, Image Handler³ does not enlarge images). If the largest image you upload is larger than these dimensions, Image Handler³ will re-size your image based on these settings. (Image Handler³ will maintain the image's aspect ratio when it re-sizes the image)

Image Dimensions

There are different approaches to setting the dimension of images.

You can do it the normal way and simply specify width and height dimensions in pixels. Set width to 100 and height to 80 for example. If your image is 200×200 it will be resized to 80×80 because this is the biggest size that fits into 100×80.

You can just set width (or height) to e.g. 100 and leave the other dimension blank (or set to 0). Now you specified a width (or height) that the image in question will be resized to. The height (or width) will be calculated according to the correct aspect ratio.

You can for example set it like the first example but append "!" to one value (for example 80! for small image height). The generated resized images are centered on a canvas that matches exactly the given size for the corresponding image. If you specified 100×80! your 200×200 image from the first example will be resized to 80×80 and placed centered on a 100×80 canvas filled with the specified background color. Think of it as kind of forcing image dimensions without messing up the aspect ratio.

More Information on Image Dimensions

If you are unsure how to set the height and width of your images, a suggested approach is to only set the width settings and leave the height blank. Image Handler³/Zen Cart will take care of correctly calculating the correct height (based on the width setting) as long as you have the following settings:

Calculate Image Size Yes

Image - Use Proportional Images on Products and Categories 1

Now the reason for suggesting to NOT set the height and to let Image Handler³/Zen Cart handle this is that most shop owners (NOT ALL) will not go through the trouble and effort to make all of their product images the same size, nor will they have the ability to calculate the correct proportional sizes for their small and medium images (relative to the large image size). So unless you are willing to take the time to calculate what your small and medium image proportions should be relative to the large product image, it's best to set the width of the small, medium and large images, leave the height blank and let Image Handler³/Zen Cart do the heavy lifting for you to automatically calculate the correct height.

Image Size Options in Configuration

A huge source for confusion is the many image size options in Admin > Configuration > Images. This section attempts to try and map out some (not all) of the various image settings to the corresponding store images.

Small Image	Product images that appear in the sideboxes (New Products, Featured Products, etc). This image setting also corresponds to the additional product images on the product info page.
Image - Product Listing	Product images which appear in the product category listing pages
Image - Product New Listing	Product images which appear in the product new listing pages
Image - Featured Products	Product images which appear in the featured product listing pages
Image - Product All Listing	Product images which appear in the all products listing pages
Product Info	Main image which appear on the product info (details) page -- AKA the medium sized image
IH small image	Settings applies to the product images that appear in the sideboxes, and all the product listing images
IH medium image	Settings applies to the product image that appears on the product info page and the rollover image displayed when hovering your mouse over the the small images.
IH large image	Settings applies to the the large product image (the one that displays when you click on the "larger image" link on the product info page)

Screenshots of Various Image Sizes

Small Product Image

Medium Product Image

Large Product Image

Sample Settings in Configuration > Images

These settings can be changed to suit your needs. These sample settings are provided here just to give you an idea of what one possible working configuration might look like. Image Settings

USAGE

Let's do a quick example. You have this nice product, took a shot with your brand new digital camera and removed the background with your favourite image manipulation program (I suggest gimp). You save this file as Portable Network Graphic (png) to keep the alpha channel, that is the transparent areas where you want to look through to your website. Let's say the image is 600 pixels wide and has a height of 800 pixels (600×800). You specified 100×80 for your small images and 150×120 for your medium sized images.

Since the product list view you use has different colors for odd and even rows, you want to keep the transparency at least for small images. You choose .png or .gif for the small image filtype and transparent for the small image background.

Now you think of your medium and large sized images. You don't want them to be in the gif format because it doesn't compress that good and you want to have more than 256 colors in your high resolution images. Further you don't care about transparency because you have just one background color in your product info page or the popup image window, so you can go with .jpg. That's what you specify for the medium and large image filetype. Let's assume you have a white background in both the product info page and the popup image window so you type 255:255:255 into the fields for medium image background and large image background.

Using Image Handler

Since Image Handler³ works mostly in the background without anybody noticing there is not much to tell. You can use Image Handler³ in two ways.

Admin > Catalog > Categories/Products
Admin > Tools > Image Handler³

When you browse your categories and products with Zen Cart's categories/products browser, you can click on the small Image Handler 3 icon between the copy- and the attributes icon to access the manager page of Image Handler³ for this specific product.

If you access Image Handler³ directly via Admin > Tools > Image Handler³, you can use it's own interface to browse categories and products.

Of course you can still upload images via the product's info pages. Image Handler³ will take care of your pictures. Image Handler³ is about choices.

Small Product Image

CREDITS & HISTORY

Based on Image Handler² Ver 2.0 Rev 7 for Zen Cart 1.3.8a updated by ckosloff.

Image Handler³ v3.0 modifications by:

nagelkruid (nagelkruid@gmail.com)
Nigelt74 (http://webzings.com)
C Jones (http://overthehillweb.com)
K Hudson

Image Handler³ v3.0 Changelog

Updated javascript file which addresses Internet Explorer 9 issue
Modify filecase management to prevent issues from uploading images with mismatched file extension case (main image is JPG, additional image is jpg) -- This change ensures that the additional images file extension will match the case of the main image (ie if main image extension is uppcase, additional images extensions will also be uppercase)
Fix fancy quotes.
Correct minor issue where image file paths would include an un-needed "/"
Add an admin configurable option whereby shopowners can choose whether or not the large or medium image will display in the "on hover" image effect
Revise module version numbering for (hopefully) the last time. Eliminating the "Rev" numbers fomat. The current version number is based on the number of releases from inception to current and what the version number SHOULD have been had a more conventional version numbering system been used for this and all prior releases
Re-format and re-write readme file. Among the changes includes:
- Better (and MORE) images
- Full integration of Tim Kroeger's AWESOME original documentation

Image Handler² Rev 8 Changelog

(Rev 8) Updated to add PHP 5.3.x compatibility (tested to for backwards compatibility through PHP 5.2.x). Lots of code in Rev. 7 was inconsistent, so this version is not only compatible with 1.3.9 and PHP5.3.x, but it will also improve performance on PHP 5.2.x Many support issues will be solved by just upgrading to Rev 8.
(Rev 8) Clean up HTML to remove deprecated HTML tags
(Rev 8) Updated javascript which now support full cross browser compatibility (tested in Chrome, Safari, Internet Explorer 8 and Firefox for Windows)
(Rev 8) No more image hotzones - The hotzone feature added no real value to Image Handler³, and it has been removed. The configuration settings for hotzones have also been removed from Admin > Configuration > Images. In case anyone is wondering, the image hover feature works just fine WITHOUT hotzones.
(Rev 8) The IH zoom medium images configuration setting has also been removed from Admin > Configuration > Images. This feature (zoom on medium images) was a future enhancement that was NEVER IMPLEMENTED in any Image Handler³ release. Continuing to leave this configuration setting in place for non-existent functionality has been a long source of confusion in the Image Handler³ support thread, and therefore it will be removed.
(Rev 8b) Corrected the following files based on current version of Zen Cart:
- admin/includes/modules/category_product_listing.php
- includes/modules/additional_images.php
(Rev 8b) Moved the following files to the correct Zen Cart override folders:
- includes/modules/main_product_image.php
  (moved to includes/modules/YOUR_TEMPLATE/additional_images.php)
- includes/modules/additional_images.php
  (moved to includes/modules/YOUR_TEMPLATE/additional_images.php)
(Rev 8b) The following were deleted from the install package (they are now obsolete)

images/zoom.png
images/medium/zoom_MED.png
images/large/zoom_LRG.png
includes/template/default_template
includes/template/classic (this folder and all the FILES in it were removed in it's entirety)

(Rev 8c) Correct minor issue where additional large images were not being watermarked in some server configurations.
(Rev 8c) Issues with some hosting configurations not setting the file permissions of the bmz_cache child folders correctly
(Rev 8c) Added .htaccess with directives to help better protect the bmz_cache folder
(Rev 8c) Correct minor issue for product names which contain single quotes.
(Rev 8d) Corrected minor issue where the "Clear Cache" function removes the .htaccess and .keep files from "bmz_cache" folder (requiring you to manually FTP these files back after clearing the cache from the admin). Clearing the cache from the IH2 admin no longer removes these files.

Acknowledgments

First, thanks to Tim Kroeger from www.breakmyzencart.com for crafting the original version of Image Handler² only on the basis of donation-ware.
Thanks to ckosloff and DerManoMann for their gracious and hard work on the Image Handler² Rev 7 and Rev 8 versions of Image Handler.
Thanks to Nigel for all of his hardwork in providing a truly cross browser compatible version of the jscript_imagehover.js and the zoom image size code.
Thanks to tophand and yellow 1912 for previous contributions to the Image Handler² codebase (from Rev 6 & 7).
Thanks to Bryan Tyler and Alex Clarke for those great add-ons to Zen Cart: Fual Slimbox and Zen Lightbox.
Thanks to nagelkruid for the refinement of the fancy quotes code.

TROUBLESHOOTING

Basics

Make sure your custom template is active. (Admin > Tools > Template Selection)

Make sure Image Handler³ is installed. Admin > Tools > Image Handler³ > Admin. Set permissions in both your images and bmz_cache folders to 755 (eg: both of these folders need to have the same permissions. For some webhosts you may have to set these permissions to 777).

If Image Handler³ does not work or gives you errors:

Make sure all files are in correct location
Make sure you uploaded ALL the Image Handler³ files
Make sure the files are not corrupt from bad FTP transfers
Make sure your file merge edits are correct
MAKE SURE YOU RE-READ THE CONFIGURATION AND USAGE SECTIONS!!!
Make sure that there are no javascript conflicts (this last point has been largely addressed since Rev 7)
Make sure that your main product image files names DO NOT contain any special characters (non-alphanumeric characters such as / \ : ! @ # $ % ^ < > , [ ] { } & * ( ) + = ). Always use proper filenaming practices when naming your images - See this document as a reference: http://www.records.ncdcr.gov/erecords/filenaming_20080508_final.pdf\

Prepare Your Site for Growth

Not many users are aware that Image Handler³ can manage the needs of a very large site as easily as it does a small one. When first building a site, the owner of a small site needs only to load images to the images folder. But when the site gets bigger and images multiply like rabbits, this can cause file naming confusions for Zen Cart and slow down the site. Preparing for your business to grow from the beginning will save you hours of work later on!

Without Image Handler³ installed, Zen Cart requires you to create, optimize, and upload three different size images for each image you want to use. You must name these images using naming suffixes, and place them in corresponding folders inside your main image folder. For example: A product called "Widget" requires images/widget.jpg (small image) images/medium/widget_MED.jpg (medium image) and images/large/widget_LRG.jpg. This is such a hassle, especially if many of your products have multiple images. And as your site grows, it becomes an impossible task!

With Image Handler³, you no longer have to make three sizes of the same images and place them in different folders (unless you want to)! Instead, you need upload only one image in one folder and Image Handler³ will do the rest! Simply upload your largest highest quality image and Image Handler³ will resize and optimize your image as needed, and serve up small, medium, or large image sizes appropriate to the page loaded - all automatically and all without actually modifying your original image file in any way! Check out the Configuration Tab of this ReadMe for more info about this awesome functionality!

Prepare your site for growth by simply creating sub-folders in your main images folder. For example, you may want to put all your "widget" images in a folder called "widgets" and all your doodad images in a folder called "doodads" , like this:

Product: Blue Widget with 3 images
----------------------------------
/images/widgets/blue_widget1.jpg (main product image for a blue widget, i.e. front view)
/images/widgets/blue_widget2.jpg (additional product image for a blue widget, i.e. side view)
/images/widgets/blue_widget3.jpg (additional product image for a blue widdget, i.e. rear view)

Product: Red Widget with 1 image
--------------------------------
/images/widgets/red_widget.jpg (main product image for a red widget)

Product: Gold Doodad with 2 images
----------------------------------
/images/doodads/gold_doodad1.jpg (main product image for a gold doodad, i.e. view from above)
/images/doodads/gold_doodad2.jpg (additional product image for a gold doodad, i.e. view from side)

Product: Silver Doodad with 3 images
------------------------------------
/images/doodads/silver_doodad1.jpg (main product image for a silver doodad, i.e. product)
/images/doodads/silver_doodad2.jpg (additional product image for a silver doodad, i.e. product detail)
/images/doodads/silver_doodad3.jpg (additional product image for a silver doodad, i.e. product's silver stamp)

Using Image Handler³, you can easily sort and manage thousands of images without confusion or hassle! When selecting the main image for a product in the Image Handler³ interface, Image Handler³ lets you pick the location for this image. This prompt disappears afterwards because Image Handler³ knows that additional images need to be in the same folder as their main product image and handles that automatically!

Zen Cart and Image Management

Image Handler³ is meant to ease the work required to setup images for your store.. It works WITH default Zen Cart functionality, it does not replace it.. Here's some additional FAQs which discuss how product images work in Zen Cart.

Information on how Zen Cart identifies/manages additional product images can be found on these Zen Cart FAQs:

Check out these FAQs and see if they help clarify how Zen Cart works with product images.

FILES

Image Handler³ makes minor modifications to some core Zen Cart files in order to work correctly. If you've installed other mods in your store, you should use a program like Winmerge or Beyond Compare to merge in the required changes for Image Handler³ into your existing store files. If this is a fresh (vanilla) Zen Cart install, you can simply overwrite the default Zen Cart files.

Here is the full list of core Zen Cart files that are affected by Image Handler³:

YOUR_ADMIN/includes/modules/category_product_listing.php
includes/modules/pages/popup_image/header_php.php
includes/modules/pages/popup_image_additional/header_php.php
includes/modules/YOUR_TEMPLATE/additional_images.php
includes/modules/YOUR_TEMPLATE/main_product_image.php
includes/templates/YOUR_TEMPLATE/popup_image_additional/tpl_main_page.php

MISC

Zen Lightbox vs. Fual Slimbox with Image Handler³

These contributions work very similarly. Both mods include jquery or mootools, keyboard navigation, etc.

In order for them to work with Image Handler³ you must merge or replace the one file Image Handler³ has in common with both of these mods, includes/modules/YOUR_TEMPLATE/additional_images.php as follows:

Zen Lightbox - Replace the additional_images.php from Image Handler³ with the one that comes with Zen Lightbox. (Zen Lightbox has included all the merged code required for Zen Lightbox and Image Handler³ to work well together)
Fual Slimbox -Look for changes marked with the text "Image Handler changes" from the additional_images.php file that comes with Image Handler³. These modifications should be merged into the additional_images.php file that comes with Fual Slimbox.
(You will need to use a file merging program like Beyond Compare or Winmerge to incorporate the Image Handler³ changes)

So test, flip a coin, then choose. The point here is that both mods work perfectly with Image Handler³.

Note: These are general instructions to help clarify how to configure these mods to use with Image Handler³. Specific lightbox configuration questions should be addressed on the support thread for the lightbox contribution, NOT on the Image Handler³ support thread.

One last thing -- Zoom on Medium Images Functionality

The code for zoom on medium images was never included in Tim Kroeger's original contribution or any subsequent Image Handler³update. It is more than likely that the reason this functionality was never included in the Image Handler³ code is largely due to the likely conflicts it would cause between the various lightbox contributions and any medium image hovering/zooming code.

Rev 6 of Image Handler² (the Image Handler² version dated Jul 16 2009) saw the introduction of the "Optional Extras" files.

For Rev 6 of Image Handler², an "Optional Extras" folder was added to the download package. The source of the updated files in "Optional Extras" folder comes from this thread:
http://www.zen-cart.com/forum/showpost.php?p=753368&postcount=4034

The documentation for these files was not clearly written, but seemed to indicate that the files in the "Optional Extras" folder provided the following functionality:

Allowing zoom behavior on medium images.
Disabling stock ZenCart "larger image" popup behavior on medium images and have Image Handler² zoom behavior applied.
Disabling zoom and "larger image" popup behavior on default (no_picture.gif) product images.

The introduction of the "Optional Extras" files to the Image Handler²codebase was both poorly documented and poorly supported by the contributing author. The little bit of documentation available also failed to clearly explain that the use of this code would disable any lightbox or jquery contributions. The "Optional Extras" files rendered these kinds of contributions non-workable.

Zen Lightbox and Fual Slimbox have been carefully crafted to be completely compatible with Zen Cart and Image Handler³. Therefore, it is NOT advised that you make the code changes required for zooming on medium images if you are using ANY kind of lightbox contribution as they will stop the lightbox from functioning correctly.

The decision to remove the "Optional Extras" folders from Rev 7 of Image Handler² wasn't just made simply because the contributors "didn't like" the feature. It was removed because --based on the related posts in the support thread-- after it's introduction, the "Optional Extras" files created more problems for store owners than actual solutions. The contributor of the "Optional Extras" code also never supported these store owners with their questions/issues. The sheer number of support posts related to problems caused by the "Optional Extras" files made it clear that it would be an unwise decision to include these files/folders in Rev 7 of Image Handler². (the version in which the "Optional Extras" files were removed from the download package)

However, for those REALLY desiring this functionality, this detailed explanation and links to the how-to instructions have been included so that anyone who would like to add these features (hover on medium images) can freely add them to their store.

Keep in mind that this code will likely interfere with the MANY contributions which affect product image behavior. For example:

Attribute image replaces main product image on selecting attribute
Attribute Pop-up (Large Images)
External Product Images
Fual Slimbox (Lightbox)
Zen Lightbox

In an analysis of the Image Handler code, it was realized that the best way to add zoom on medium images and still provide support for those store owners who like/want lightbox features (and other similar product image effects) would probably require incorporating all of these features directly into the Image Handler codebase. To maintain full store owner control and flexibility, the Image Handler codebase would also probably also have to include the following features:

Admin configurable zoom on medium images
Admin configurable lightbox effects
The ability for zoom on medium images to work if lightbox features are activated.

Based on this analysis, it was determined that in order to make these changes the RIGHT WAY (AKA not in a hacky sub-standard manner) which will keep the module in a sustainable/supportable state required a lot more coding work than ckosloff and Mano were willing/able to invest on a volunteer basis.

All involved in this module's support and update are aware that improvements can be made to Image Handler³. The current updates to Image Handler³ were not designed to produce a re-written version of Image Handler. The purpose was to provide a leaner/cleaner set of download files, with much clearer directions that would not lay waste to the work of other popular contributions that currently work with Image Handler³. (for example, Fual Slimbox and Zen Lightbox). The intent of the Rev 8 releases were meant to further the code cleanup from Rev 7 along with incorporating PHP 5.3.x compatibility.

So in the end the work of adding zoom on medium images functionality is left to anyone else in the open source community who wants to tackle a REAL re-write (versus a hacked set of files) of Image Handler³ to fully incorporate (and hopefully SUPPORT) the addition of these features. Yes, it's open source software and while anyone certainly can add a hack to cobble in zoom on medium images, bundle it up and submit it to the downloads section; most of these kinds of hacked contributions usually go largely unsupported by the author of the hacked version and generally only serve the person who submits the hacked version.

Since Image Handler has always been a well written contribution, any added functionality should be included in the same careful manner. Following this development approach ensures that this open source application remains usable for the WIDEST possible audience out the box. Hacked additions often do not take this community interest into consideration.

In the meantime, for those who desire zoom on medium images, this section of the readme with links to the thread which shows how to add zoom on medium images along with the appropriate cautions about incompatibility with lightbox and other similar contributions should provide the basic information needed to add this functionality to Image Handler³. If you make these changes, you will also need to run the Image Handler³ uninstall, then update the admin/includes/functions/extra_functions/functions_bmz_image_handler_update.php to re-add the zoom configuration options back to Image Handler³, and then re-run the Image Handler³ install again.

Fancy image functions such as image zooming on hover are really just extra features. Nice to have features for sure, but they are not "THE reason" (nor the REAL purpose) to use Image Handler³.

LICENSE

Image Handler³ is released under the General Public License (see LICENSE.txt)

This script is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Always backup your shop and database before making changes.

Calculate Image Size	Yes
Image - Use Proportional Images on Products and Categories	1