Version: 1.3
Release: Jun 2, 2006
Compatibility: QC v1.0+
Languages: en
Author: Wizzud
Contact: rb@wizzud.com

Image Watermark

Plugin module for Quick.Cart by OpenSolution.org

Synopsis

Ths plugin can apply a watermark to your PNG and JPG format images, effectively hiding the image path in the process. It does not affect the images stored on disk, but modifies images on-the-fly as they are requested by browsers. You can select whether to apply watermarks to product images and/or content/category images. Thumbnails can also be watermarked, with a different image if required. Watermarks can be positioned using left-center-right and top-middle-bottom combinations.
NEW in v1.1! 'Lightbox' effect for your images replaces the standard Quick.Cart gallery. This uses Lightbox v2.02 to provide excellent resizing and opacity effects, including a Caption and Next/Previous links where appropriate.
NEW in v1.1! Watermark capability has been extended to cover the Last Product and Random Product plugins.
* Please note the Prerequisites for running this plugin. Due to the complexity of the interaction with the core Quick.Cart code it is necessary to use the facilities provided by the Plugin Manager. If this causes any problems I apologise in advance, but it is unavoidable.

Compatibility

Quick.Cart versions prior to v1.0 : Not compatible.
Quick.Cart versions 1.0 upward : Compatible at the time of writing.
Product Attributes Plugin : Due to the Prototype Javascript Framework used for the Lightbox effect, if you are running Product Attributes you must upgrade to at least v2.2 of the Product Attributes plugin.
Other Plugins : At the time of release, this plugin has no compatibility problems with any other known plugin.

Prerequisites

Plugin Manager v2.0+ : Uses the Plugin Manager's 'extendTplParser' class extension.
None other, assuming that the Compatibility requirements have been met.

Upgrade

There is an upgrade path starting with version 1.0 of this plugin.

Upgrading v1.2 to v1.3

The files that have changed are
  • /plugins/imageWatermark/AboutThisPlugin.html
  • /plugins/imageWatermark/imageWatermark.php
  • /plugins/imageWatermark/setup.php
You can, if you wish, simply unzip the v1.3 release file, find these files, and add to or overwrite the v1.2 versions with the updates. Then you only need to complete step (b) below; otherwise, you should follow the full upgrade instructions below.

Upgrading v1.1 to v1.3

The files that have changed are
  • /plugins/imageWatermark/AboutThisPlugin.html
  • /plugins/imageWatermark/lightbox.js New!
  • /plugins/imageWatermark/effects.js New!
  • /plugins/imageWatermark/prototype.js New!
  • /plugins/imageWatermark/imageWatermark.php
  • /plugins/imageWatermark/setup.php
  • /templates/imageWatermark.tpl
  • /templates/admin/imageWatermark.tpl
And these files have been removed:
  • /plugins/imageWatermark/lightbox.js.php
  • /plugins/imageWatermark/effects.js.php
  • /plugins/imageWatermark/prototype.js.php
You can, if you wish, simply unzip the v1.2 release file, find these files, and add to or overwrite the v1.1 versions with the updates. Then you only need to complete step (b) below; otherwise, you should follow the full upgrade instructions below.

Upgrading v1.0 to v1.3

  1. Take a note of the plugin's current configuration settings and then follow steps 1, 2, 3 and 4 of the Installation instructions below, replacing old files/folders with the new versions. If you have made your own modifications to previous v1.0 files, re-apply changes as necessary!
  2. Go to the Configuration - Plugins option on the Admin menu. You will see a warning that the Image Watermark plugin version number has changed. If Plugin Manager has been configured for Version Checking then the plugin will also have been disabled and the Configuration button greyed out.
    • Click the Reload Setup button for the Image Watermark plugin
    • Click the Configuration button for the Image Watermark plugin, make any changes necessary, and Save
    • Re-enable the plugin, and Save

Install

Where possible, the release folder is laid out in the correct folder structure to aid installation.
  1. Copy the entire imageWatermark folder from the release/plugins/ folder into your Quick.Cart plugins/ folder.
  2. Copy the contents of the release/templates/admin/ folder to your Quick.Cart templates/admin/ folder (2 new files: imageWatermark.tpl and imageWatermark.css).
  3. Copy the contents of the release/templates/ folder to your Quick.Cart templates/ folder (2 new files, NOT the Admin folder!).
  4. Due to the use of the Prototype JavaScript Framework, if you plan to enable the Lightbox Gallery you must make one change to js/checkForm.js or your form validation will not work. You have a choice of either (a) or (b) below:
    1. EITHER : I have provided a modified version of checkForm.js which you can simply use to overwrite your existing one. The file provided is based on the one from QCv1.2, but can be used in QCv1.0 or 1.1 with abslutely no problem:
      Copy the contents of the release/js/ folder to your Quick.Cart js/ folder (1 file: checkForm.js)
    2. OR : Edit js/checkForm.js (taking a copy first) and look at roughly line 186 for
      CODE
      if( aA[i][1] )
         sT = aA[i][1];
      else
         sT = false;
      Replace with these lines
      CODE
      /* Wizzud ...*/
      if(oO){
         if( aA[i][1] )
           sT = aA[i][1];
         else
           sT = false;
      }else{
         sT = true;
      } /*... /Wizzud */
  5. Go to the Configuration - Plugins option on the Admin menu, and configure and then enable the imageWatermark plugin.

User Guide

Configuration

The plugin's configuration parameters are accessible via the Plugin Manager, and full explanations have been provided for each and every setting. Please read them carefully! You should note in particular that you can turn off the watermarking for all images and just run the Lightbox Gallery; similarly, you can just enable watermarking without having the Lightbox Gallery.
For your information only, the plugin's configuration page has also been set up to show the GD package version, and its support (or lack of) for both PNG and JPG graphics formats.

Lightbox Gallery

The Lightbox Gallery effect replaces the standard Quick.Cart gallery for full size images. Next/Prev links are provided for photos within a Product or a Category, as with the standard gallery it replaces. It is also applied to the Administration forms for Product and Category maintenance, on both small and big images, with Next/Prev links between the two.
Please Note : The Lightbox effect does not play well with animated GIFs in certain browsers, and the opacity effect is browser dependent.
Credits:

Watermark Image

The watermark image itself can be either a PNG or JPG format, non-transparent graphic. The colour Grey (#808080) is rendered transparent in the composite image so I suggest making this your background colour and making the actual watermark image some other colour or shade of grey. I have provided 4 PNGs and a JPG as examples:
  • watermark.png - The text 'WaterMark' in Alba font, light grey
  • watermarkCopyright.png - A Copyright symbol, suitable for thumbnails?
  • watermarkLines.png - 6 horizontal dark grey lines
  • watermarkDark.png - A darker version of watermark.png
  • watermark.jpg - A JPG version of watermark.png
The resultant composite image is produced in the same format as the original image, not the format of the watermark image. So even if you apply a PNG watermark to a JPG image, the result will be a JPG. Speaking of JPG format, the quality of any resultant JPG format image can be set from the configuration settings for the plugin - it defaults to 75 (out of a possible 100).
When designing your watermark image you should be aware that the bigger and more complex your watermark is, the more processing power/memory is required to construct the composite image. A large watermark image can slow down the return of the requested image to a noticeable extent, so some experimentation may be required if the display of your watermarked images is being delayed.
The watermark image is expected to be found in the imageWatermark plugin sub-folder (eg. plugins/imageWatermark/watermark.png). There is no upload facility included with the plugin so you will have to FTP your image(s) into this folder. Then, simply change the file name(s) in the plugin configuration via Configuration - Plugins from the Admin panel.
NOTE: The plugin does not have the capability to handle transparent images (ie. the image to which the watermark is being applied) and any resultant image will appear black. This is also the case with Quick.Cart itself, when producing thumbnails from transparent PNGs. If you require transparent images, make them GIFs, which are unaffected by watermarking.

How Does it Work

Basically, the 'src' attribute of images is set to index.php?p=watermarkAAbCCd instead of the path to the image. The browser's call to index.php to get the image is then intercepted by the plugin's actions_client.php module, and the 'AAbCCd' part of the URL is used to determine which image is being asked for and in what form (big or thumbnail). If the watermark can be applied (PNG or JPG requested image) and should be applied (configuration settings) then it is, and the resultant composite is returned. GIFs are returned unaffected, as are any other images which are configured not to be watermarked. To effect this, there are intercepts on any template call that involves a PHOTO* block.

Language

By default this plugin is only supplied with an English language file - /plugins/imageWatermark/lang-en.php.
If you wish to provide translations for your own language, copy lang-en.php to lang-[2-char-code].php (within the same folder), where [2-char-code] is the recognised code for your language. For example, a Polish language file would be /plugins/imageWatermark/lang-pl.php.
The plugin will automatically load the English file first, and then look for the language file in the Shop's configured language, so that the English text is always there as a backup.
Please note that the Next/Prev links for the Lightbox Gallery are background images, specified in the imageWatermark.css stylesheets, and the Close link is an image specified in the Configuration section at the top of /plugins/imageWatermark/lightbox.js.php. If you wish to replace them with non-English versions you will need to provide alternatives for closelabel.gif, nextlabel.gif, and prevlabel.gif in the /plugins/imageWatermark/ folder.

Change Log

Version 1.3

  • Code : fixed a bug when using Lightbox with watermarks set to Not Thumbnails - the watermark was not being produced on the large image.
  • Setup : upped version number.
  • Documentation : updated to v1.3.

Version 1.2

  • Code : fixed a bug when used in conjunction with Last Product and/or Random Product plugins, whereby all product images got set to the one picked by the most recently activated of Last/Random Product.
  • Script : switched the prototype, effects and lightbox scripts back to plain javascript files (.js suffix) - so the .js.php versions are now redundant.
  • Templates : modified both the shop and admin versions of imageWatermark.tpl to call the correct script files (above).
  • Setup : upped version number.
  • Documentation : updated to v1.2.

Version 1.1

  • Code : added support for the Lightbox effect; added support for the images produced by the Last Product and Random Product plugins
  • Templates/CSS : shop and admin template file and css file to support Lightbox effect
  • Setup : upped version number and added actions_admin.php
  • Documentation : updated to v1.1.
~~ The End ~~