Node Image Gallery with ImageField

When image-sets are discussed it's usually in the context of a full featured photo gallery, but there's another common use: including a set of images with the content of a node. For example, product images with a product node or a "mini" photo album with an article. The CCK ImageField combined with a jQuery module like Thickbox makes adding image-sets to nodes easy. Here's how.

Overview

This "recipe" describes how to add a gallery style photo-set to a node. This photo-set stands apart from the node content as a set of thumbnails which can be clicked on to display the full-size version. The Thickbox slide-show feature is also implemented so viewers are able to step through the full-size version of the pictures without exiting the viewer. Although Thickbox is used, this technique should be easily adoptable to different plug-ins.

An example of the technique can be seen here: Finding the Blue Whale

We create the gallery by adding a CCK ImageField to the target node and theming it. That's it. Thanks to ImageCache, ImageField, and Thickbox module integration, the rest is configuration.

The following modules are required:

• CCK
• ImageField (requires File Field)
• ImageCache (requires Image API)
• Thickbox

The steps are:

1. Create ImageCache preset for a thumbnail picture
2. Add a CCK ImageField to the target node type to hold the photo-set
3. Theme the ImageField

Before you start, decide:

• Maximum size for picture
• Thumbnail size

Other Notes:

• This technique works well for a relatively small amount of pictures. The Edit Node user interface for Image Field becomes unruly for picture management when you add a lot of images.
• The file used to theme the gallery image field is an almost line-for-line copy of the Views Grid View theming file, which creates a HTML table with one picture per cell. If you want different theming you should have enough information to implement it after reading this article.
• In order for CCK theming to work, you need to have a copy of content-field.tpl.php in the theme directory.
• Thickbox displays the image title field with the large version of the image. Though technically a title, it can also be used more like a caption. It's simply a matter of length.

Detailed Set Up

For the purposes of this demo I've created a content type called "article". The mini-gallery can be attached to any node type, and even multiple node types. Images sizes are set so a full sized picture can be no larger than 1024x768 pixels. The thumbnails are scaled to 200 pixels wide.

Modules

Install, enable, and configure the following modules:

• CCK
• FileField
• ImageField
• ImageCache
• ImageAPI + ImageAPI GD2 or ImageAPI ImageMagick
• Thickbox

Image Cache Preset

Create the Image Cache preset for the module:

1. Go to Home > Administer > Site building > ImageCache
2. Add new preset: thumb200w
3. Add Scale: Width: 200 to the preset
   

Image Field

Adding a "mini-gallery" image field to the node:

1. Go to Home > Administer > Content management > Content Types
2. Go to Manage Fields for Article (or your target node type)
3. Add an ImageField named Mini Gallery
   
4. Mini-Gallery Image Field settings:
   Maximum resolution for Images: 1024x768
   Title text settings: Enable custom title text
   Number of values: Unlimited
5. Go to Display Fields tab
6. Under the Basic settings for field Mini Gallery:
   Label: Hidden
   Teaser: Check Excluded checkbox
   Full node: Select Thickbox: thumb200w image
   
7. Under RSS settings for field Mini Gallery:
   thumb200w image linked to image
8. If you are using Content permission, set the user permissions for the new content field.

Theme the Image Field

To theme the image field to appear as shown in the example:

1. Copy content-field.tpl.php from sites/all/modules/cck/theme to your theme directory. A quirk in CCK field theming requires this file to exist in your theme directory before any other CCK theme files are recognized.
2. Create a file named content-field-field_mini_gallery.tpl.php
3. Add the following code:
   <?php
// $Id:$

/**
 * @file content-field-field_mini-gallery.tpl.php
 * Theme implementation to display multiple values in the mini-gallery field.
 *
 * Available variables:
 * - $node: The node object.
 * - $field: The field array.
 * - $items: An array of values for each item in the field array.
 * - $teaser: Whether this is displayed as a teaser.
 * - $page: Whether this is displayed as a page.
 * - $field_name: The field name.
 * - $field_type: The field type.
 * - $field_name_css: The css-compatible field name.
 * - $field_type_css: The css-compatible field type.
 * - $label: The item label.
 * - $label_display: Position of label display, inline, above, or hidden.
 * - $field_empty: Whether the field has any valid value.
 *
 * Each $item in $items contains:
 * - 'view' - the themed view for that item
 *
 * @see template_preprocess_content_field()
 */
  $columns = 4;
  $rows = array_chunk($items, $columns);
?>
<?php if (!$field_empty) : ?>
<table class="mini-gallery">
  <tbody>
    <?php foreach ($rows as $row_number => $columns): ?>
      <?php
        $row_class = 'row-' . ($row_number + 1);
        if ($row_number == 0) {
          $row_class .= ' row-first';
        }
        if (count($rows) == ($row_number + 1)) {
          $row_class .= ' row-last';
        }
      ?>
      <tr class="<?php print $row_class; ?>">
        <?php foreach ($columns as $column_number => $item): ?>
          <td class="<?php print 'col-'. ($column_number + 1); ?>">
            <div class="photo-image"><?php print $item['view']; ?></div>
            <div class="photo-title"><?php print $item['data']['title']; ?><div>
          </td>
        <?php endforeach; ?>
      </tr>
    <?php endforeach; ?>
  </tbody>
</table>
<?php endif; ?>
   
   The code is also available in a downloadable file. Drupal mungs the name, so you'll need to remove some underscores if you use it directly.
4. Refresh the cache so Drupal sees the change.
5. Depending on how your theme displays tables, you may need some addition CSS to complete the formatting.

Notes:

• If you turn on the CCK ImageField description or alt attributes, they can be accessed in the theme file in the $item['data'] variable.
• This theming applies to any instance of the mini-gallery field on any node. In other words, by theming the CCK field, you don't have to theme the images in any node template files.