Skip to content

Configuration

Jump to bottom
lat9 edited this page Oct 22, 2025 · 8 revisions

This page contains information regarding the configuration of IH5. Here are some "quick" links, since the sidebox table-of-contents can be overwhelming:

Configuration :: Images

Image Handler5 works out of the box. There's no need to configure anything if you are ok with the presets, but if you want to change the way IH deals with your images navigate to your Zen Cart admin's Configuration :: Images (after installation!).

If you are using Fual Slimbox or ColorBox for Zen Cart with IH5, be sure to read this section.

IH5 creates images (based on your image settings) in the bmz_cache directory. It does not replace or modify the original images. You can use the IH5 admin-level image manager without using any of the storefront image-related features.

The IH installation adds settings to your admin's Configuration :: Images page, as shown below. IH Configuration

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

  • cache-file naming method
  • preferred filetypes
  • compression quality
  • background color
  • watermarking
  • 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 results in a force-canvas-size mode. Images are re-sized 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 this document's Image Dimensions section.

Cache File-Naming Conventions

Starting with IH5, you can choose the naming convention used for re-sized files created by the image-handler, one of Hashed, Readable or Mirrored.

Hashed

This is the convention used by image-handler versions prior to 4.3.4. The handler uses an MD5 hash to compress the resized file's original path, name and parameters to produce file names similar to 8240eb50da20af3ecec990d3e56099fa.image.50x40.gif in the directory bmz_cache\8. It can be "very difficult" to determine which original file is associated with that resized file!.

If you are currently using an Image Handler version prior to 4.3.4, this naming-convention will be initially configured on your IH upgrade. Some stores use HTML img tags in their category and/or product descriptions that reference an image's "hashed" name and this default is set to ensure that downward compatibility.

Readable

This is the convention introduced image-handler versions later than 4.3.3. The handler concatenates the original file's path, name and parameters to produce file names similar to matrox-mg400-32mbgif.image.50x40 in the directory bmz_cache\m. It's a little easier to determine which original file is associated with that resized filename!

If you are performing an initial install or upgrading Image Handler from a version later than 4.3.3, this naming will be initially configured for your IH5 installation.

Mirrored

This is a convention introduced with image-handler version 5.1.9. The handler concatenates the original name and parameters to produce file names similar to Readable. The difference is that instead of storing the files under a single letter directory (the first character of the file name), The files are stored in a mirror of the original directory structure. This is useful if you have many images that start with the same letter allowing them to be spread through directories as the original files.

For example: If you have a file called matrox.gif in the directory images\Graphics\cards You would create a file like matrox-mg400-32mbgif.image.50x40.gif in the directory bmz_cache\Graphics\cards.

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 IH5-generated files (the ones stored in the bmz_cache directories) will be created using the filetype you specify in these settings.

Let's say that you want the large and medium images to be .png files:

  1. Choose .png for your IH medium images filetype and IH large images filetype settings.
  2. Leave the small image at the default setting of no_change.
  3. Upload a .jpg file to the product you are updating.

IH5 will

  1. Generate .png image files for your large and medium product images regardless the format of the original image (in this example a .jpg).
  2. Since no_change was selected for your small images, the small product image will be a resized .jpg.

The filetype feature provides another means to let IH5 do some of the heavy lifting for you. Instead of having to convert your 1000 .jpg product images to .png's, you can let IH5 do this work 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 ...

The various images' sizes you can have a "mixed bag". For example, you might 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: IH5 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 (e.g. the main image is a jpg and the additional images are png). IH5 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:

  1. GIF is good for small thumbnails and features some basic transparency.
  2. JPG doesn't feature transparency, but has a very good file quality/compression ratio, especially for photographic images. This would be your desired filetype for large and possibly medium sized images.
  3. PNG files feature alpha-transparency and as many colors as jpg but are generally larger in filesize than both jpg and gif. Older versions of Internet Explorer had issues displaying alpha-transparency, so you better stick with gif, if you need transparency and support those older IE versions.

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 loss-less 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 image size by specifying the color's RGB-value separating each color component (red, green and blue) by a colon. The color component's values each 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 are a few sources for obtaining RGB values. Color Schemer even provides a really nice HEX/RGB conversion calculator.

  1. https://cloford.com/resources/colours/500col.htm
  2. https://www.computerhope.com/htmcolor.htm

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 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 fully 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 must be present. That means you have to upload files to the following specific locations:

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

IH5 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 and the images are generated accordingly. You can specify where you want the watermark to appear on the image canvas by your choice of Watermark Gravity, one of:

  1. NorthWest
  2. North
  3. NorthEast
  4. West
  5. Center
  6. East
  7. SouthWest
  8. South
  9. SouthEast

To use your own watermark, simply create your own replacement watermark images using the image editing software of your choice and overwrite the supplied ones. Your custom watermark files must be PNGs and overwrite the sample watermark images.

Please note that questions about how to create watermarks should not be posted on the support thread. There are tons of sources on the web which can provide you good guidance on creating watermarks, just Google How to create watermarks.

Image Dimensions

There are different approaches to setting the dimension of images.

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

  2. You can set the width (or height) to a specific value, e.g. 100, and leave the other dimension blank (or set to 0). The height (or width) will be calculated according to the correct aspect ratio.

  3. If you append an exclamation-point (!) to one value (e.g. 80!), the generated re-sized images are centered on a canvas that matches exactly the given size for the corresponding image. If you specified 100x80!, a 200x200 image will be resized to 80x80 and placed centered on a 100x80 canvas filled with the specified background color. Think of it as kind of forcing image dimensions without messing up the aspect ratio.

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 associated height blank. An image's height will be correctly calculating (based on the width setting) so long as you have set:

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

The reasoning here 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 IH5 and Zen Cart do the heavy lifting for you to automatically calculate the correct height.

Image Size Options (Configuration)

A huge source for confusion is the many image size options in the admin's Configuration :: Images. Here are some of the image-size options on that page and where they are used:

Configuration Setting Where Used
Small Image Product images that appear in the sideboxes (New Products, Featured Products, etc) or are additional product images on a product details page (e.g. product_info, product_music_info).
Image - Product Listing Product images that appear in the product category listing pages.
Image - Product New Listing Product images that appear on the new-products' listing page (products_new).
Image - Featured Products Product images that appear on the featured-products' listing page (featured_products).
Image - Product All Listing Product images that appear on the all-products' listing page (products_all).
Product Info The main product-image that appears on a product-details page — a.k.a. the medium image.
IH small image Product images that appear in the sideboxes and all the product-listing images.
IH medium image Product image that appears in a product's details page and the rollover image displayed when hovering your mouse over the the small images.
IH large image The large product image, the one that displays when you click on the "larger image" link on a product's details page.

Clone this wiki locally