Overview

Have you ever wanted to use Image API to combine several images (deltas) of an image field into a single horizontal or vertical image?

If so, Image Combination Effects (ICE) is the module for you!

If not, you might be wondering why you would ever want to do this. With some creative use of CSS + JavaScript, this technique can be used to cut down on the number of requests a browser has to make in order to display multiple images. This technique is often referred to as "spriting" when used for icons and other small images used throughout a site, but there are other times when you might want to do this for larger images as well.

We created this module for an upcoming site that needs to display a slideshow consisting of four large images. We wanted to cut down on the number of requests necessary for the slideshow to load, so that all images are available together (i.e. we couldn't have any unexpected gaps in the slideshow). At the same time, we needed the customer to be able to upload new slideshow images and customize the slideshow order. The Image module was the logical choice for this.

How to Use

Follow these steps:

1. Install the ImageCache Actions module and this module just like any other (i.e. unpack the modules into the sites/all/modules or sites/yoursite/modules folders) and enable them (admin/modules).
2. Create an image style that contains all of the effects you would like to apply to every image that will be combined into the output image. For example, you may want to scale and crop each image to a specific size.
3. Add the "Combine images" effect as the very last effect in the image style. On the settings page for the effect, pick in which direction you would like the images to be laid out.
4. Create a content type that has an image field that accepts multiple values.
5. Modify the field display settings of the image field to use the image style created in step 2.
6. Enjoy!

In step 2, consider how each effect applied to an individual image will affect the output image. For example, applying a "Scale and Crop" effect to make each individual image 320x240 will produce an output image that is 960x240 when applied to an image field with three images when ICE is configured to layout horizontally, and an image that is 320x720 when ICE is configured to layout vertically.

Only the first delta (i.e. the first image of the field) will be rendered with the image style, since ICE combines all the images in one pass. The remaining deltas will be prevented from rendering separately. If you ever remove the ICE effect from the image style, Drupal will go back to rendering all of the deltas.

Known Limitations

• ICE must be placed last in the list of effects for an image style to guarantee each individual image will be displayed properly. Some effects, like "Desaturate" or "Scale", can be applied after ICE to operate on the combined image, but not all effects are guaranteed to work.
• Every image is scaled and cropped to match the size of the first image, after the first image has been run through all of the effects that precede ICE in the image style. This is done to make the images uniform and greatly simplify the logic that places the images. This means that you cannot create a combined image in which each part of the image is a different size.
• Images cannot overlap or be placed in any other arrangement other than horizontally or vertically. You may be able to simulate a fancy arrangement using the "Rotate" effect before ICE.
• Images that fail to load will be replaced with a black square.
• ICE has only been tested with the GD toolkit.
• ICE currently depends on the ImageCache Actions module and its ImageCache Canvas Actions sub-module.

Credits

Module originally created by Guy Paddock of RedBottle Design.

Sponsored by Max Rochester.

Module icon generously provided by The Iconshock Blog.