Image Handler5 for Zen Cart v1.5.5 (and later)

Version 5.1.6 by lat9

Current Support Thread at Zen Cart Forums: https://www.zen-cart.com/showthread.php?222983-Image-Handler-5-(for-v1-5-5)-Support-Thread

Notes:

  1. The majority of this readme, other than installation instructions and change history, has been migrated online to the plugin's GitHub repository. That enables the readme to be updated as-required without the need to provide a plugin update for documentation corrections.
  2. Change history prior to v5.0.0 of IH5 has been archived on the plugin's GitHub repository.

Overview

Image Handler5 (IH5) simplifies the management of product images (particularly additional product images) and helps to improve page performance by optimizing those images. Product images (based on your image settings) are created in the Image Handler5 bmz_cache directory. The original images are not modified, so it's perfectly safe to use on an existing store.

Image Handler5 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 as they're required. You can simply upload just one image or you can have different sources for medium and large images. Image Handler5 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 or add additional images without having to do this manually via FTP. IH5 works fine with mass update utilities like EZ-Populate and the Database I/O Manager (DbIo).

For additional information, please refer to the documentation on the plugin's GitHub repository; see above for the link.

This section identifies the procedure you'll use to install, upgrade or remove the plugin for your Zen Cart.

Requirements
  • Zen Cart v1.5.5 or later (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 ColorBox for Zen Cart with Image Handler5 you must read the "Misc" tab.

In order to resize and modify images, Image Handler5 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

Starting with v5.0.0, Image Handler5 no longer requires core-file overwrites, but there are two (2) template-override files required:

  1. /includes/modules/YOUR_TEMPLATE/additional_images.php
  2. /includes/modules/YOUR_TEMPLATE/main_product_image.php

Note: Those template-file changes are included in the "base" Zen Cart distribution, starting with Zen Cart v1.5.6!

In all cases, the changes that IH5 requires are additions of Zen Cart "notifiers" to allow IH5 to do its job in a seamless manner. The changes required do not affect the functionality of the modules and can be left safely in place if you decide to uninstall Image Handler.

The IH5 installation provides updates (see below for additional information) for two of the more popular large-image viewers: Fual Slimbox and ColorBox for Zen Cart. Those updates contain plugin-specific modules that work in conjunction with the newly-added IH5 "notifiers".

What all that techno-babble means for your IH5 installation (or upgrade!) is that there are two installation routes, dependent on whether you use a large-image viewer and, if so, which one …

Regardless the route you choose, I highly recommend an initial installation 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 route works for IH5 installation/upgrade into stores that have either no modifications or only Fual Slimbox or ColorBox changes to those two template-override files.

Just install or upgrade Image Handler5 — see below — and it will work. If your admin is in a language other than english then read further down for additional instructions.

Route 2

This route works for stores that have additional changes (i.e. another large-image viewer) or if you are unsure of the changes to those two template-override modules.

Review the installation instructions below. Once you have unzipped the IH5 package, use a file-comparison program (like WinMerge or Beyond Compare) to merge the template-override changes required by IH5 with your template's pre-existing changes.

Fual Slimbox or ColorBox for Zen Cart with Image Handler5

Both of these plugins provide a large-image popup using jQuery methods and are pre-integrated with IH5. IH5 was validated using Fual Slimbox v2.0.1a and ColorBox for Zen Cart v2.1.1 on Zen Cart 1.5.5e.

When your store is using IH5 along with one of these plugins, the order in which the plugin and IH5 are installed is important:

If your store … … then …
… has an existing installation of either large-image popup plugin … Install IH5 as if you had a "fresh" Zen Cart installation, overwriting (or creating) the two template-override files required by IH5.
… has an existing installation of IH5 and you are now going to install one of the large-image popup plugins … Install the large-image popup as instructed but do not overwrite the two template-override files required by IH5. The IH5 installation already included modules that enable that large-image popup to do its thing.
… has neither IH5 nor an existing large-image popup plugin … Install IH5, copying all its distributed files, then proceed to install the large-image popup plugin as described above.

IH5's distribution contains the following files that provide its interoperability with these two large-image popup plugins. If your store uses a different popup plugin, you'll need to review the code associated with one of the plugin integrations provided.

Plugin Name /includes/auto_loaders File /includes/classes/observers File
Fual Slimbox config.fual_slimbox.php FualSlimboxObserver.php
ColorBox config.colorbox.php ColorBoxObserver.php
Installation/Upgrade Instructions
  1. BACK UP your database & store.
  2. BACK UP your database & store!!!!!
  3. BACK UP your database & store!!!!!
  4. Unzip the Image Handler5 package to your local hard drive, retaining the directory structure.
  5. Within the 1_Installation_Files (v1.5.5) directory:
    1. Rename the YOUR_ADMIN directory to match the name of your Zen Cart admin directory.

      IMPORTANT!!!: If your shop is using languages other than english, you must also copy the contents of the YOUR_ADMIN/includes/languages/english directory to YOUR_ADMIN/includes/languages/YOUR_LANGUAGE for each additional language.
    2. For Zen Cart versions prior to v1.5.6, rename the two (2) YOUR_TEMPLATE directories to match the name of your currently-active Zen Cart template:
      1. /includes/modules/YOUR_TEMPLATE
      2. /includes/templates/YOUR_TEMPLATE
  6. Once you've gotten any file-merge changes completed (i.e. you're using installation route 2), log in to your store's admin.
  7. Next, using an FTP program, upload the files from the 1_Installation_Files (v1.5.5) directory to your store's web-hosted root directory. Do not upload the 1_Installation_Files (v1.5.5) directory, just the contents of this directory.
  8. 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 or upgrade.
  9. Navigate to Admin > Configuration > Images, set IH resize images to yes.
  10. If you followed all instructions to the letter, you are ready to move on to the online documentation to learn how to modify the default configuration settings.

Un-Install Instructions

Note: IH5's uninstall processing is provided as a separate script, so you can use your admin's Admin / Admin Profiles tool to restrict its usage to authorized admin-users.

  1. BACK UP your database and store.
  2. Log into your Zen Cart admin and navigate to Tools > Image Handler5 and:
    • Click the "Admin Tools" link at the top of the page.
    • Click the "Uninstall Image Handler" link at the top of the page.
    • You'll be presented an Uninstall Image Handler page. To continue with the uninstall, click the "Go" button; to cancel, click the "Cancel" button.
    • You'll be presented a confirmation page. Click "Go" one more time and the uninstall script will remove all files (except for the list below) in the IH5 distribution as well as the changes it makes to the database.
    The following files remain after IH5 is uninstalled:
    1. /includes/auto_loaders/config.colorbox.php (remains only if ColorBox is installed)
    2. /includes/auto_loaders/config.fual_slimbox.php (remains only if Fual Slimbox is installed)
    3. /includes/classes/observers/ColorBoxObserver.php (remains only if ColorBox is installed)
    4. /includes/classes/observers/FualSlimboxObserver.php (remains only if Fual Slimbox is installed)
    5. /includes/modules/YOUR_TEMPLATE/additional_images.php
    6. /includes/modules/YOUR_TEMPLATE/main_product_image.php

This section identifies the files added or modified for this plugin as well as the plugin's change history.

The plugin provides the following files in its distribution zip-file.

File Name Comments
/bmz_cache/.htaccess  
/images/watermark.png  
/images/medium/watermark_MED.png  
/images/large/watermark_LRG.png  
/includes/auto_loaders/config.colorbox.php Added in v5.0.0.
/includes/auto_loaders/config.fual_slimbox.php Added in v5.0.0.
/includes/auto_loaders/config.image_handler.php Added in v5.0.0.
/includes/classes/bmz_gif_info.class.php  
/includes/classes/bmz_image_handler.class.php  
/includes/classes/observers/ColorBoxObserver.php  Added in v5.0.0.
/includes/classes/observers/FualSlimboxObserver.php Added in v5.0.0.
/includes/classes/observers/ImageHandlerObserver.php Added in v5.0.0.
/includes/extra_configures/bmz_image_handler_conf.php  
/includes/extra_configures/bmz_io_conf.php  
/includes/extra_datafiles/image_handler_logging.php Added in v5.1.0.
/includes/functions/extra_functions/functions_bmz_image_handler.php  
/includes/functions/extra_functions/functions_bmz_io.php  
/includes/modules/YOUR_TEMPLATE/additional_images.php This is the Zen Cart 1.5.6 version of the module.
/includes/modules/YOUR_TEMPLATE/main_product_image.php This is the Zen Cart 1.5.6 version of the module.
/includes/templates/YOUR_TEMPLATE/css/style_imagehover.css  
/includes/templates/YOUR_TEMPLATE/jscript/jscript_imagehover.js  
/YOUR_ADMIN/image_handler.php  
/YOUR_ADMIN/image_handler_uninstall.php Added in v5.0.0.
/YOUR_ADMIN/image_handler_view_config.php Added in v5.0.1.
/YOUR_ADMIN/includes/ih_manager.php  
/YOUR_ADMIN/includes/auto_loaders/config.image_handler.php  
/YOUR_ADMIN/includes/classes/ImageHandlerAdmin.php Added in v5.0.0. Contains functions used by image_handler.php, moved from that module.
/YOUR_ADMIN/includes/extra_configures/bmz_image_handler_conf.php  
/YOUR_ADMIN/includes/extra_configures/bmz_io_conf.php  
/YOUR_ADMIN/includes/extra_datafiles/image_handler.php  
/includes/extra_datafiles/image_handler_admin_logging.php Added in v5.1.0.
/YOUR_ADMIN/includes/functions/extra_functions/functions_bmz_image_handler.php  
/YOUR_ADMIN/includes/functions/extra_functions/functions_bmz_io.php  
/YOUR_ADMIN/includes/init_includes/init_image_handler.php  
/YOUR_ADMIN/includes/languages/english/image_handler.php Added in v5.0.0.
/YOUR_ADMIN/includes/languages/english/image_handler_about.php Added in v5.0.1.
/YOUR_ADMIN/includes/languages/english/image_handler_uninstall.php Added in v5.0.0.
/YOUR_ADMIN/includes/languages/english/image_handler_view_config.php Added in v5.0.1.
/YOUR_ADMIN/includes/languages/english/extra_definitions/bmz_image_handler.php Comments only for v5.0.0; definitions moved to image_handler.php.
/YOUR_ADMIN/includes/languages/english/extra_definitions/bmz_language_admin.php Comments only for v5.0.0; definitions moved to image_handler_extra_definitions.php.
/YOUR_ADMIN/includes/languages/english/extra_definitions/image_handler_extra_definitions.php Added in v5.0.0.
  • v5.1.6, 2019-10-03:
    • BUGFIX: Include required parameter in additional_images notifier.
    • BUGFIX: Correct formation of 'image-hover' links.
    • CHANGE: Use CSS buttons instead of images (thanks, @proseLA!).
    • CHANGE: Use HTML5 'doctype'.
    • BUGFIX: Correct target page for category/product search; it changed for zc156 and later.
    • The following files were changed (all in the 1_Installation_Files (v1.5.5) directory):
      1. /includes/classes/bmz_image_handler_class.php
      2. /includes/modules/YOUR_TEMPLATE/additional_images.php
      3. /YOUR_ADMIN/image_handler.php
      4. /YOUR_ADMIN/image_handler_uninstall.php
      5. /YOUR_ADMIN/image_handler_view_config.php
      6. /YOUR_ADMIN/includes/init_includes/init_image_handler.php
  • v5.1.5, 2019-07-24:
    • BUGFIX: Correct undefined "IH_VERSION" PHP Notice on initial installation.
    • BUGFIX: Correct undefined index on initial installation; missing a configuration setting's description.
    • The following files were changed (all in the 1_Installation_Files (v1.5.5) directory):
      1. /YOUR_ADMIN/includes/init_includes/init_image_handler.php
      2. /YOUR_ADMIN/includes/languages/english/extra_definitions/image_handler_extra_definitions.php
  • v5.1.4, 2019-07-11:
    • BUGFIX: Correct "missing constant" PHP warning on initial installation.
    • BUGFIX: Correct edit product link; broken by zc156 Categories / Products restructuring.
    • BUGFIX: Correct "Can't determine the page link" on new product-image creation.
    • BUGFIX: Correct various PHP Notice logs.
    • BUGFIX: Correct 'force canvas' and proportional height/widths image creation.
    • BUGFIX: Correct image-generation for products that can't be added to the cart.
    • The following files were changed (all in the 1_Installation_Files (v1.5.5) directory):
      1. /includes/classes/bmz_image_handler.class.php
      2. /includes/functions/extra_functions/functions_bmz_image_handler.php
      3. /YOUR_ADMIN/image_handler.php
      4. /YOUR_ADMIN/includes/ih_manager.php
      5. /YOUR_ADMIN/includes/init_includes/init_image_handler.php
      6. /YOUR_ADMIN/includes/languages/english/image_handler.php
  • v5.1.3, 2019-05-01:
    • BUGFIX: Correct upgrade from IH versions that didn't include an IH_VERSION value.
    • BUGFIX: Correct overlapping previous/next product buttons on Zen Cart 1.5.6 and later.
    • CHANGE: PSR-2 standardization.
    • BUGFIX: Correct image auto-update conditional.
    • The following files were changed (all in the 1_Installation_Files (v1.5.5) directory):
      1. /includes/classes/bmz_image_handler.class.php
      2. /includes/modules/YOUR_TEMPLATE/additional_images.php
      3. /YOUR_ADMIN/image_handler.php
      4. /YOUR_ADMIN/includes/init_includes/init_image_handler.php
  • v5.1.2, 2019-02-24:
    • BUGFIX: Correct undefined LARGE_IMAGE_WIDTH and _HEIGHT constants.
    • BUGFIX: Correct configuration_description for small/medium/large image backgrounds.
    • BUGFIX: Correct ih_log*.log contents when DIR_FS_CATALOG is set to '/'.
    • BUGFIX: Suppress image-conversion errors, recording only when the IH debug is active.
    • BUGFIX: Correct invalid numeric issues for later versions of PHP.
    • BUGFIX: Move "new file" button in Tools->Image Handler5 to improve workflow.
    • The following files were changed (all in the 1_Installation_Files (v1.5.5) directory):
      1. /includes/classes/bmz_image_handler.class.php
      2. /includes/classes/observers/FualSlimboxObserver.php
      3. /YOUR_ADMIN/image_handler.php
      4. /YOUR_ADMIN/includes/init_includes/init_image_handler.php
      5. /YOUR_ADMIN/includes/languages/english/image_handler.php
  • v5.1.1, 2018-06-20:
    • BUGFIX: Correct 'bmz_cache' file location when DIR_FS_CATALOG is set to '/'.
    • BUGFIX: Image-add corrections.
    • BUGFIX: Correct debug-log generated on initial entry.
    • The following files were changed (all in the 1_Installation_Files (v1.5.5) directory):
      1. /includes/classes/bmz_image_handler.class.php
      2. /YOUR_ADMIN/includes/ih_manager.php
      3. /YOUR_ADMIN/includes/init_includes/init_image_handler.php
  • v5.1.0, 2018-05-29:
    • CHANGE: Added View Image Handler Configuration to the IH5 admin menu.
    • CHANGE: Removed Scan for old images tool from the IH5 admin menu.
    • BUGFIX: Invalid "quality" parameter supplied to imagepng, resulting in oversized images being created.
    • CHANGE: Move Image Handler5 help-text to a separate language file.
    • BUGFIX: Background checker not recognizing "transparent" (with no RGB) as a valid setting.
    • BUGFIX: Notifiers in the additional- and main-product-image modules need to be "globalized".
    • BUGFIX: Check for the presence of the zen_lightbox function before enabling the Fual Slimbox observer.
    • CHANGE: Major admin-level restructuring and additional logging for debug.
    • CHANGE: Remove 'allow_mixed_case_ext' handling.
    • BUGFIX: Correct interaction with Zen ColorBox.
    • BUGFIX: Correct 'missing' definition.
    • BUGFIX: Correct unwanted PHP warning when product-image is set, but missing.
    • CHANGE: Add admin-activity record when an admin clears the bmz_cache.
    • The following files were changed (all in the 1_Installation_Files (v1.5.5) directory):
      1. /includes/classes/bmz_image_handler.class.php
      2. /includes/classes/observers/ColorBoxObserver.php
      3. /includes/classes/observers/FualSlimboxObserver.php
      4. /includes/classes/observers/ImageHandlerObserver.php
      5. /includes/extra_configures/bmz_image_handler_conf.php
      6. /includes/extra_datafiles/image_handler_logging.php (Added)
      7. /includes/functions/extra_functions/functions_bmz_image_handler.php
      8. /includes/functions/extra_functions/functions_bmz_io.php
      9. /includes/modules/YOUR_TEMPLATE/additional_images.php
      10. /includes/modules/YOUR_TEMPLATE/main_product_image.php
      11. /YOUR_ADMIN/image_handler.php
      12. /YOUR_ADMIN/image_handler_uninstall.php
      13. /YOUR_ADMIN/image_handler_view_config.php (Added)
      14. /YOUR_ADMIN/includes/ih_manager.php
      15. /YOUR_ADMIN/includes/classes/ImageHandlerAdmin.php
      16. /YOUR_ADMIN/includes/extra_datafiles/image_handler.php
      17. /YOUR_ADMIN/includes/extra_datafiles/image_handler_admin_logging.php (Added)
      18. /YOUR_ADMIN/includes/init_includes/init_image_handler.php
      19. /YOUR_ADMIN/includes/languages/english/image_handler.php
      20. /YOUR_ADMIN/includes/languages/english/image_handler_about.php (Added)
      21. /YOUR_ADMIN/includes/languages/english/image_handler_view_config.php (Added)
      22. /YOUR_ADMIN/includes/languages/english/extra_definitions/image_handler_extra_definitions.php
  • v5.0.0, 2017-11-10:
    • Major changes to the plugin's distribution, installation and uninstall procedures.
      1. Drops support for Zen Cart versions prior to 1.5.5.
      2. Installation no longer auto-removes the plugin's installation/upgrade modules.
      3. No more core-file overwrites; only two template-override file changes needed.
      4. Includes integration with Fual Slimbox and ColorBox.
      5. Separate uninstall script included.
    • Correct javascript error in imagehover processing.
    • Detect and correct invalid transparency settings.
    • Use CSS3 media-queries to "hide" imagehover pop-up on smaller devices.
    • Restore search functionality.

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)
  • lat9 (https://vinosdefrutastropicales.com)
  • Chad M (mc12345678@cox.net)

and Image Handler5 modifications by:

  • lat9 (https://vinosdefrutastropicales.com)
  • jazzman346 (https://github.com/jazzman346)
  • jeking (https://www.zen-cart.com/member.php?16702-jeking)
  • Zen4All (https://github.com/Zen4All)