Image Handler 2.0

by Tim Kröger (


This upgrade 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. This upgrade further enables you to watermark your images (overlay a second specific translucent image) and have medium images pop up when you move your mouse over a small image (fancy hover). Have a look at the showcase to get a first impression of the looks.

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 2 works fine with mass update utilities like EzPopulate.


For recent updates of this contribution please visit The most recent version of this document can be found at

Support is available in the following forum thread at

or in the breamyzencart forums at but you will be able to reach a much greater user-base at the zen-cart forums.


Warning: This is work in progress. Image Handler has been tested to some degree and works as expected under most conditions. Nevertheless it may contain errors. Before you use this upgrade on a live site, you should test it in a safe environment. I urge you to backup your database. Before you continue to install it into your zen-cart folders make a backup of your complete shop system.

I will not be held responsible for any damage this contribution may or may not do to you, your operating system, your installation of zen-cart or your website.


Precautions: Backup your shop and database.


In order to resize and modify images, Image Handler 2 needs either GD libraries (since version 2) or ImageMagick (since version 6) installed. You can check if your version of PHP includes the GD libraries by going to Admin → Tools → Server Info and searching for GD. You have to ask your host (or read your site’s documentation), to learn about an ImageMagick installation. If you want to render GIF images, you need to have GD libraries version 2.0.28 or newer installed.

Short Version (don't do this on a live site)

Copy the following directories into your Zen Cart folder.

  • admin
  • bmz_cache
  • images
  • includes

Make sure that the bmz_cache folder’s permissions match those of your images folder (e.g 0777, 0775 or 0755).


Go to Admin → Tools → Image Handler 2 → Admin and click Install Image Handler

If you use a custom template, copy the contents of includes/templates/templates_custom into your custom template’s folder or merge the files if the target files have already been customized.

Long Version

Check if this contributions would overwrite any files that you modified, if you would upload it to your server. That means you have to compare the folder containing your changes to this contribution’s folder. The folders you need to upload to your server are the following.

  • admin
  • bmz_cache
  • images
  • includes

Make sure that the bmz_cache folder’s permissions match those of your images folder (e.g 0777, 0775 or 0755).

If everything went fine, You will have a new entry called Image Handler 2 inside the Tools menu of your Zen Cart admin interface. Select this link to request the Image Handler admin tool. There are four tabs on that page from which you select Admin to display some administrational functions regarding Image Handler 2. Select Install Image Handler and the installation is complete.

If you use a custom template, copy the contents of includes/templates/template_custom into your custom template’s folder. If you have modified any of the files located in this contribution’s includes/templates/template_custom folder, you need to merge these files (popup_image_additional/tpl_main_page.php in particular) with those of your custom template.


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, there are two places where you can configure it.

  • Configuration File
  • Images Configuration page

Configuration File

Ok, there’s this admin/includes/extra_configures/bmz_image_handler_conf.php file. You shouldn’t change anything in there unless you really know what you’re doing. The parameters are explained in that file.


Images Configuration page

This is the known admin → Configuration → Images page inside your admin interface. A few parameters have been added where 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 and zooming overlays

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.

Preferred Filetypes

You can select either .png, .jpg, .gif or no_change for every image size type. Uploaded images are kept as they are, but the generated files feature the filetype you specify here. 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.

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)

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.


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)

I included 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, switch off, 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 Wartermark Gravity setting.

Zooming (fancy hover effect)

When selecting this feature for small images, the medium image pops up whenever you move your mouse cursor over the small image. Those images are branded with an overlay just like a watermark to indicate the pop up ability. You can upload a file to images/zoom.png to have it overlay your image. A small image is included for quick start. If you don’t want the overlay to show but still want the effect, just delete the overlay image.

You can select the gravity just like you can with the watermark to configure where the overlay should go. In addition to that you can specify if you want the overlay to act as a hotzone. That means the popup only shows if you move your mouse exactly above the overlay image (hotzone). If it does not, the whole image is the hotzone.

Note: Zooming in on medium images is not implemented, yet.

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.


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 2


When you browse your categories and products with Zen Cart’s categories/products browser, you can click on the small icon between the copy- and the attributes icon to access the manager pager of Image Handler for this specific product. If you access Image Handler 2 directly via Admin → Tools → Image Handler 2, you can use it’s own interface to browse categories and products. Image Handler is about choices.

Of course you can still upload images via the product’s info pages. Image Handler will take care of your pictures.


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. Internet Explorer still cannot render png images with transparency so you’ll have to stick to gif. You choose .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.

Recent changes RSS feed Valid XHTML 1.0 Valid CSS