## Image Handler4 for v1.5.x

Support thread: http://www.zen-cart.com/forum/showthread.php?t=194740
Download link: http://www.zen-cart.com/index.php?main_page=product_contrib_info&products_id=2098

- Purpose & Aim
- Install/Uninstall
- Configuration
- Usage
- Credits & History
- Troubleshooting
- Files
- Misc
- License

### PURPOSE & AIM

Image Handler4 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 Handler4 generates product images (based on your image settings) in the Image Handler4 bmz_cache folder. It DOES NOT replace or modify the original images. So it's PERFECTLY safe to use on an existing store.

Image Handler4 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 Handler4 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 Handler4 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 original images are retained.
- Easy install. Built in auto-installer backs up core files before overwriting them and automatically writes to your database.
- Easy uninstall. Built in auto-uninstaller restores core files from back-ups it made during installation and removes itself from your database.
- 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 (optional).
- 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 Handler4 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 Handler4. 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 Handler4.

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

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

!!READ EVERYTHING!!

After following the installation instructions, it is very strongly recommended that you read through the ENTIRE "Configuration" & "Usage" sections of this readme. There you will find out exactly what Image Handler4 can do.

Ready to get started? Just follow the installation instructions.

### INSTALLATION

!!!!!BACKUP YOUR STORE BEFORE YOU BEGIN!!!!!

BEFORE INSTALLING, you are strongly encouraged to READ ALL OF THE TABS in this readme file. Then follow the installation or upgrade instructions, as appropriate.

### BEFORE YOU POST A QUESTION ON THE FORUM - read through this readme again as needed

Two sets of installation instructions have been provided - one for advanced users and one for those who are new to Zen Cart and/or Image Handler4. Please use which ever set you feel most comfortable with.

In both cases, the installation process for Image Handler4 is completely different than that of previous versions. Be sure to read the installation instructions before you begin.
Requirements

- Zen Cart v.1.5.x (not backwards compatible with older versions of Zen Cart)
- Either GD libraries version 2 or greater, or ImageMagick version 6 or greater
- If you are using Fual Slimbox or Zen Lightbox with Image Handler4 you MUST read the "Misc" tab.

In order to resize and modify images, Image Handler4 needs either GD libraries or ImageMagick 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.

BEFORE YOU INSTALL READ THIS!!!

Some files that Image Handler4 modifies are core files. This means that Image Handler4 overwrites the existing files that Zen uses. If your site has no modifications to these files then there are no problems. If your installation has existing modifications to you files then you will have to carefully merge the existing modifications with the modifications that Image Handler4 makes. There are a number of ways of approaching this.

The BEST recommendation is to do this on a development version of your site. If you are serious about running your store it is always worth having a second version of the store so that you can experiment on that first. I know that this seems like a lot of work but it really is worth it and does not actually take that much time.

## Route 1

This works for installations that have no modifications.

Just install Image Handler4 and it will work. If your admin is in a language other than english then read this thread for instructions.

## Route 2

This works well if you know that you have files to merge and is a good option if you don't know if you have merges to do.

Install as normal. The installer will create backups of any files it overwrites. So, just go for it. Then check your site. If everything is working well then you are good to go and you didn't need to do merges.

If problems have been created it probably means that you have merges to do. So, you can look on the server and find the backup versions of the files that have been created by Image Handler4. Download the backup version (this will have your previous modifications). Download the active version (this will have the Image Handler4 modifications) . Merge these two files and upload the result as the active file.

## Route 3

This is the way to go if you know that you have merges to do.

Read the installation instructions and see which Image Handler4 files are equivilant to which Zen Cart files. It is not a complex pattern! Then merge your modifications into the appropriate file in the Image Handler4 installation files.

For instance if you have existing modifications in
/YOUR_ADMIN/includes/modules/category_product_listing.php
merge them with the installation file
/YOUR_ADMIN/includes/modules/category_product_listing_IH4.php
Then install as normal.

At a high level what happens during the install is this:

- The files are uploaded to the "wrong" place.
- A backup of your existing files is created
- Then your files are overwritten in the "right" place

The logic of the auto-installer is based on the fact that less experienced users have been known to upload files and overwrite existing file modifications. And those modifications may or may not be correctly backed up. There is potentially no recovery from this. Creating a backup before overwrite means that recovery is possible. However, to allow files to be backed up, the Image Handler4 files cannot be uploaded into the 'right' place because that is potentially destructive. So, they are put in an alternate position and during the auto installation the files are then moved into the right place (once the backup has been created).

New Installation Instructions

1. BACK UP your database & store.
2. BACK UP your database & store!!!!!
3. BACK UP your database & store!!!!!
4. Unzip the Image Handler4 package to your local hard drive, retaining the folder structure.
5. Rename the "YOUR_ADMIN" folder in the "1_Installation_Files" folder to match the name of your admin folder.
   IMPORTANT!!!: If your shop is using a language other than english, you MUST also copy the contents of YOUR_ADMIN/includes/languages/english files to YOUR_ADMIN/includes/languages/YOUR_LANGUAGE
6. DO NOT rename, remove, or relocate any of the other files or folders. Doing so WILL cause the auto-installer to fail.
   You may notice files that look familiar, except that they contain an "_IH4" suffix. For example: /YOUR_ADMIN/includes/modules/category_product_listing_IH4.php. Such files are an important part of the auto-installer and should NOT be renamed!
   You may notice folders named "IH_INSTALL" that contain files that would normally be in the "YOUR_TEMPLATE" folder. Such folders and the files they contain are an important part of the auto-installer and should NOT be removed, renamed, or relocated!
   The auto-installer will write to the files that need to be written to, create the files that need to be created, and ensure those files are in their appropriate folders.
   The ONLY thing you need to do to have a successful installation is rename your admin folder copy the language files (if applicable) and follow the steps below.
7. Take a look at the table below. If any of the files in the right column have been customized by you or modified by other module installs, you will need to use a file merging program like Beyond Compare or Winmerge so that you can incorporate those changes BEFORE you upload them and complete the installation. Make your file merges to the files indicated in the left hand column below. DO NOT rename, remove, or relocate any of these files or folders. Doing so may cause the auto-installer to fail.
   Optionally you can perform the file merges to the files created by Image Handler4 AFTER you install Image Handler4.
   Some filepaths and files have changed. Please use the filemap below to assist you.

   IH4 Installation Package Files | Maps to These Files in Your Store
   /YOUR_ADMIN/includes/modules/category_product_listing_IH4.php | /YOUR_ADMIN/includes/modules/category_product_listing.php
   /includes/modules/pages/popup_image/header_php_IH4.php | /includes/modules/pages/popup_image/header_php.php
   /includes/modules/pages/popup_image_additional/header_php_IH4.php | /includes/modules/pages/popup_image_additional/header_php.php
   /includes/modules/IH_INSTALL/additional_images.php | /includes/modules/YOUR_TEMPLATE/additional_images.php
   /includes/modules/IH_INSTALL/main_product_image.php | /includes/modules/YOUR_TEMPLATE/main_product_image.php
   /includes/templates/IH_INSTALL/popup_image_additional/tpl_main_page.php | /includes/templates/YOUR_TEMPLATE/popup_image_additional/tpl_main_page.php

8. Once you've gotten your files merge changes completed, log in to your store's admin.
9. Next, using an FTP program, upload the files from "1_Installation_Files" to your store -- DO NOT upload the "1_Install_Files" folder, just the CONTENTS of this folder
   (copy ALL of the add-on files to your store!! Most issues are caused by store owners who decide to NOT load ALL of the module files)
10. Return to your store's admin and click on any link. If you followed the instructions above, you will see a message in the message stack at the top of your admin screen confirming a successful install.
11. Navigate to Admin > Configuration > Images, set "IH resize images" to "yes".
12. If you followed all instructions to the letter, you are ready to move on to the Configuration tab to learn how to modify the default configuration settings.

If you are using Fual Slimbox or Zen Lightbox with Image Handler4 you MUST follow the instructions in the "Misc" tab regarding using either of these mods with Image Handler4.

Upgrade Instructions

Image Handler4 was built specifically for Zen Cart v.1.5.x. As such, it is not backward compatible to lower versions of Zen Cart, nor are lower versions of Image Handler (Image Handler2 & Image Handler3) compatible with Zen Cart v.1.5.x.

If you have made the mistake of installing a version of Image Handler3 that has been hacked up to function with Zen Cart v.1.5.x, DO NOT attempt an upgrade!! You MUST do a complete uninstall of the hacked up version of Image Handler3 and do a fresh NEW install of Image Handler4, following the instructions above.

Attempting an upgrade on an unsupported version of Image Handler will likely cause issues, and these issues will NOT be supported in the Image Handler support thread!!

Un-Install Instructions

1. BACK UP your database & store.
2. The Image Handler4 auto-uninstaller will replace all the files it over-wrote during installation with the back-ups it made prior to overwriting them, thereby restoring them to their pre-IH state. Before proceding with the uninstall, take a look at the following files from your current Zen Cart installation. If any of them have been customized by you or modified by other module installs after Image Handler4 was installed, you will need to make note of those changes so that you can restore them
   after the uninstall has been completed.
   - /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
3. If you have not made any changes to the above files since installing Image Handler4, then simply proceed to the next step and let the auto-uninstaller do it's thing.
4. Log in to your admin and navigate to Tools > Image Handler4
5. In the Image Handler4 Manager, click on the "Admin" link
6. Click on ""Remove Image Handler from database".
7. In the message stack at the top of the Admin screen, you will see a message confirming a successful uninstall.
8. Remember: If, in Step 2, you determined that any of the listed files had been modified by you or another addon since installing Image Handler4, you will need to incorporate those customizations back in to the files now.
9. The Image Handler4 auto-installer leaves behind some benign files and folders that Zen Cart will ignore. However, if you prefer to remove them, it is safe to delete them manually:
   - store_root/bmz_cache directory & files
   - admin/images/.picasa.ini
   - admin/includes/modules/category_product_listing.php.OLD.IH4
   - admin/includes/modules/category_product_listing.php_IH.OLD.IH4
   - includes/modules/IH_INSTALL (empty directory)
   - includes/modules/pages/popup_image/header_php.php.OLD.IH4
   - includes/modules/pages/popup_image/header_php.phpIH.OLD.IH4
   - includes/modules/pages/popup_image_additional/header_php.php.OLD.IH4
   - includes/modules/pages/popup_image_additional/header_php.phpIH.OLD.IH4
   - includes/templates/IH_INSTALL (empty directory)
10. If you were using Fual Slimbox or Zen Lightbox with Image Handler4 you MUST re-upload the /includes/modules/YOUR_TEMPLATE/additional_images.php file from Fual Slimbox or Zen Lightbox fileset or your lightbox won't function as expected.

### CONFIGURATION

Image Handler4 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.

If you are using Fual Slimbox or Zen Lightbox with Image Handler4 you MUST read the "Misc" tab.

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

With Image Handler4 it is possible to use the Image Handler4 image manager WITHOUT using the image caching features. If you choose to install Image Handler4 and ONLY use the image manager, please note that NONE of Image Handler4image management features will be available (including the image hover features)

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 Handler4 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 Handler4 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 you want the large and medium images to be .png files:

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

This will result the following:

- Image Handler4 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 Handler4 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 Handler4 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 Handler4 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

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 Handler4 willallow 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 Handler4 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 Handler4 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 Handler4 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, SouthWest, South and SouthEast for the Watermark Gravity setting.

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 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 Handler4 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 Handler4 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 Handler4 will not enlarge your image (Again, Image Handler4 does not enlarge images). If the largest image you upload is larger than these dimensions, Image Handler4 will re-size your image based on these settings. (Image Handler4 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 Handler4/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 Handler4/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 Handler4/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 appears 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

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.

### 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 favorite 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 filetype 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

There are two ways to use Image Handler4:

- Admin > Catalog > Categories/Products
- Admin > Tools > Image Handler4

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 page of Image Handler4 for this specific product.

If you access Image Handler4 directly via Admin > Tools > Image Handler4, you can use it's own interface to browse categories and products or to add, change, or delete images from your products.

The Image Handler4 interface is designed to be highly intuitive and easy to use. Referencing the image above, you can see that all the action takes place on the "Manager" tab of the interface. For example:

- You can browse through your product categories using the "Previous" and "Next" buttons
- You can select a specific product category using the product category dropdown list and allowing the page to refresh & display all the products in that category
- You can select a specific product to view, add, or edit (change or delete) its image(s) by selecting the category, then highlighting the product that appears in the list, and clicking the "Display" button.
- You can even jump to the "Edit Products" or "Product Attribute" pages by clicking either of those buttons

It's all very straightforward. But let's talk about where some folks get stuck: adding primary and additional product images. Let's begin by walking through the process of adding an image to a product. The important thing to understand is that the process is the same whether you're adding your first image or your tenth to a given product

- Select the product you want to add an image to and click the "New File" button to the right of the product information
- Select the image directory from the dropdown list where you want the image to be stored on your server
- Click on the Default image file's "browse" button to navigate to the image you want to upload. It is best to upload the largest version of your image because this is the file that Image Handler4 will use to create small, medium, and large versions of that image.
- Click "Save". Notice that after clicking "Save", the page refreshes and you can now see your image(s) and all the sizes your image(s) will display as throughout various areas of your store.

Important Notes:

- You do not need to add an image to the "Medium" or "Large" fields unless you want your medium and large product images to be different images than that of your small product images.
- Image Handler4 will take care of creating small, medium, and large versions of the large image you uploaded, using the image size settings you specified in admin > configuration > images when you configured Image Handler4after install.
- Attempting to add an image in the "Medium" or "Large" fields without FIRST populating that "Default" field will result in an error. You MUST always upload an image to the "Default" field - whether it is your first product image or your hundredth.
- The "Medium" and "Large" fields are not the appropriate place to add your additional product images. Remember that the process for adding primary and additional images is the same. The "Default" field must be used
- "Default" does not refer to "Primary Image". "Default" only refers to the image file you upload that Image Handler4 will use to make small medium and large versions of your image(s).
- If all this talk about "primary images", "additional images", "large, medium, and small images", etc. has your head spinning, visit the "Troubleshooting" tab of this readme and look at the "Prepare Your Site For Growth" section to gain a deeper understanding.
- REPEATING: The process of adding an image is the same for both primary and additional images, You must use the "Default" field, and "Default" only refers to the image file you upload that Image Handler4 will use to make small medium and large versions of your image(s).

Next, let's walk through the process of changing a product's primary or additional image.

- Select the product whose image you'd like to change.
- Click the Action/info icon to the right of the image you want to change (whether it is the primary image or an additional image)
- Click the "Edit" button
- Click the Default image file's "browse" button to navigate to the image you want to upload, remembering that it is best to upload the largest version of your image because this is the file that Image Handler4 will use to create small, medium, and large versions of that image.
- Click the "Save" button

Finally, let's talk about those buttons and fields we skipped over, what they do, and how to use them.

- The Action/info icon allows you to access the "edit" and "delete" buttons. We've already discussed the "edit" button and the "delete" button should be self explanatory.
- The optional "Image base name" (which only appears when adding a new primary image file) allows you to name your image something other than its filename. Leaving it blank results in your image file being uploaded with it's current filename.
- The optional "Image Suffix" (which only appears when adding a new additional image file) allows you to add your preferred suffix to your additional images (in order to link your primary and additional images together for a given product). Or if you prefer, leave it blank and let Image Handler4 create a suffix for you.
- As previously discussed, the "Medium" and "Large" image fields that you see when you add or edit an image are to be used if you want your medium and large product images to be different images than that of your small product images.

Of course you can still upload images via the product's info pages and Image Handler4 will take care of them for you. Image Handler4 is about choices.

### CREDITS & HISTORY

Based on Image Handler2 Ver 2.0 Rev 7 for Zen Cart 1.3.8a updated by ckosloff.
Image Handler4 v4.0 modifications by:

- nagelkruid (nagelkruid@gmail.com)
- Nigelt74 (http://webzings.com)
- C Jones (http://overthehillweb.com)
- K Hudson (http://empowermentsanctuary.com)
- N Collie (http://www.clearright.co.uk)
- Jörg Schönberger (http://www.webchills.at)

Image Handler4 v4.1 Changelog

- Backup files generated by the auto-installer are now given the OLD.IH4 extension instead of the BAK extension (which some server configurations disallowed)
- Configuration settings are now consistently and correctly appended to the default Images configuration section
- Updates to the readme file.

Image Handler4 v4.0 Changelog

- Updated to work with Zen Cart v1.5 (not backwards compatible!!)
- Cleaned up some of the old outdated crap from the fileset. (Yes it's the end of the --who knows why it was here in the first place-- .keep file!!!)
- Made changes to image_handler.php file just to get rid of the sections that were to do with install and uninstall.
- In addition to that stupid .keep file all of the thumbs.db have been deleted too
- Addition of autoinstaller
- The install has been cleaned up as well to make sure that obsolete image configuration settings are removed if someone was running an OLD version of Image Handler prior to installing this new version.
- Updates to improve error handling including improved better on-screen text to deter improper image uploads
- Removed all hardcoded text and moved to proper language files.
- Re-format and re-write readme file. Among the changes includes:
  - Installation instructions now include both a short version of instructions for advanced users, as well as a step-by-step guide for those new to Zen Cart and/or Image Handler4
  - Uninstall instructions now include a step-by-step guide to successfully uninstalling Image Handler4for those new to Zen Cart and/or Image Handler4
  - Detailed, step-by-step instructions have been provided for use of the Image Handler4 interface in Admin > Tools > Image Handler4, with a particular focus on the image upload process

Image Handler3 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 (i.e. if main image extension is uppercase, 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 format. 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 Handler2 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 Handler3, 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 Handler3 release. Continuing to leave this configuration setting in place for non-existent functionality has been a long source of confusion in the Image Handler3 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 Handler2 only on the basis of donation-ware.
- Thanks to ckosloff and DerManoMann for their gracious and hard work on the Image Handler2 Rev 7 and Rev 8 versions of Image Handler.
- Thanks to Nigel for all of his hardwork in providing improvements in the error messaging output, and creating 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 Handler2 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 N. Collie for the KICK ASSED autoinstaller program making image Handler easier than EVER to install!!!
- Thanks to ScriptJunkie for taking on the job of updating the readme when my schedule got in the way of doing it!!
- 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 Handler4 is installed. Admin > Tools > Image Handler4 > Admin. Set permissions in both your images and bmz_cache folders to 755 or 777, depending on what your webhost allows. (Both of these folders need to have the same permissions).

If Image Handler4 does not work or gives you errors:

- Make sure all files are in correct location
- Make sure you uploaded ALL the Image Handler4 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
- 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 Handler4 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 Handler4 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 Handler4, 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 Handler4 will do the rest! Simply upload your largest highest quality image and Image Handler4 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 widget, 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 Handler4, you can easily sort and manage thousands of images without confusion or hassle! When selecting the main image for a product in the Image Handler4 interface, Image Handler4 lets you pick the location for this image. This prompt disappears afterwards because Image Handler4 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 Handler4 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.

- Image Preparation - How-to
- My images are distorted/fuzzy/squished, help?

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

- Why am I seeing images for other products on my product pages?
- How do I add multiple images to a product?
- How do I add more than one image of a product? I want to have a main image and also one or two other images that show more parts of a particular product. How/where do I add additional images to a product page? Thanks!

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

### FILES

Image Handler4 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 Handler4 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 Handler4:

- /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 v1.6.3_1.5a vs. Fual Slimbox with Image Handler4

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

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

- Zen Lightbox v1.6.3_1.5a - If Zen Lightbox v1.6.3_1.5a was installed before Image Handler4, then you will need to replace the additional_images.php from Image Handler4 with the one that comes with Zen Lightbox. Simply rename the additional_images.php file that comes with Zen Lightbox to match the filename of the equivilent file in the Image Handler4 install fileset and upload to the correct location. (see the mapping table on the installation tab to see where this file should go) Zen Lightbox has included all the merged code required for Zen Lightbox and Image Handler4 to work well together.
  If you are installing Image Handler4 and Zen Lightbox v1.6.3_1.5a together, then install Zen Lightbox after you install Image Handler4 and just replace the Image Handler4 additional_images.php file with the one from Zen Lightbox.
- Fual Slimbox -Look for changes marked with the text "Image Handler changes" from the additional_images.php file that comes with Image Handler4. 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 Handler4 changes)

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

Note: These are general instructions to help clarify how to configure these mods to use with Image Handler4. Specific lightbox configuration questions should be addressed on the support thread for the lightbox contribution, NOT on the Image Handler4 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 Handler3update. This has not changed in Image Handler4. The history of this functionality can be found below, for those who are interested.

It is more than likely that the reason this functionality was never included in the original 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 Handler2 (the Image Handler2 version dated Jul 16 2009) saw the introduction of the "Optional Extras" files.

For Rev 6 of Image Handler2, 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 Handler2 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 Handler2codebase 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 Handler3. 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 Handler2 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 Handler2. (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:

1. Attribute image replaces main product image on selecting attribute
2. Attribute Pop-up (Large Images)
3. External Product Images
4. Fual Slimbox (Lightbox)
5. 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:

1. Admin configurable zoom on medium images
2. Admin configurable lightbox effects
3. 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 Handler3. The current updates to Image Handler3 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 Handler3. (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 Handler3 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 Handler3. If you make these changes, you will also need to run the Image Handler3 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 Handler3, and then re-run the Image Handler3 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 Handler3.

### LICENSE

Image Handler4 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.