Use the WordPress Media Title and/or Caption Fields for Gallery Image Captions

custom-gallery-image-captions-wordpress-plugin-README.md

Custom WordPress Gallery Image Captions

If you want customise your gallery captions using any of the image meta data, follow these instructions as an example how-to.

---

Updates

On 20 February 2020, I proposed a pull request for this enhancement.

As of March 2020, this code is now available as a plugin on the WordPress.org plugin directory! The plugin name is Gallery Image Captions or GIC.

GitHub Repo

---

Instructions

1. Place the contents of the custom_gallery_image_captions_functions.php file in your child theme's functions.php file.
2. Copy /wp-includes/media.php gallery_shortcode() function to your child theme's functions.php file.
3. Rename copied function. E.g. my_gallery_shortcode
4. In the renamed function, replace the existing code block that creates the captiontag markup with the contents of the custom_image_caption_filter_hook_media.php into your copy of gallery_shortcode() function. Grep/search on captiontag to find where the code should go. See snippet below of the code to overwrite.
5. Add the following above your new custom function in functions.php.

/**
 * Override the WordPress core media.php gallery_shortcode().
 */
remove_shortcode('gallery', 'gallery_shortcode');
add_shortcode( 'gallery', 'my_gallery_shortcode' );

6. Use the classic or Gutenberg editor or your fave page builder to create an HTML block. Add your classic gallery shortcode e.g., [gallery size="medium" columns="3" link="file" ids="29,30,31"] or [gallery size="large" columns="3" link="file" ids="29,30,31" captiontag="h4"]

Snippet to Replace in the gallery_shortcode() Function

Find this snippet in your copy of the gallery_shortcode() function and replace it with the contents of custom_image_caption_filter_hook_media.php.

		if ( $captiontag && trim( $attachment->post_excerpt ) ) {
			$output .= "
				<{$captiontag} class='wp-caption-text gallery-caption' id='$selector-$id'>
				" . wptexturize( $attachment->post_excerpt ) . "
				</{$captiontag}>";
		}

		$output .= "</{$itemtag}>";

---

Gallery Styling

Styling can be specified a couple ways. First, in the shortcode.

[gallery itemtag="div" icontag="span" captiontag="p"]

More details in the Codex.

Second, using custom CSS to override the default class attributes.

/**
 * Styling based on article "How To: Style Your WordPress Gallery"
 * by Par Nicolas.
 * 
 * https://theme.fm/how-to-style-your-wordpress-gallery/
 */

/* Mobile Portrait Breakpoint - 1 column */
@media only screen and (max-width: 719.998px) {
  .gallery-columns-3 .gallery-item { 
	 width: 100% !important; 
  }
}

/* Mobile Landscape and Tablet Breakpoints - 2 columns */
@media only screen and (min-width: 720px) and (max-width: 1024px) {
  .gallery-columns-3 .gallery-item { 
	 width: 50% !important; 
  }
}

---

Tested on WordPress 5.3.2 running on PHP 7.3.5.

custom_gallery_image_captions_functions.php

<?php

/**
 * Get Image Meta
 */
function get_image_meta($postvar = NULL)
{
    if (!isset($postvar)) {
        global $post;
        $postvar = $post->ID;
    }

    $attachment = get_post($postvar);

    return array(
        'alt' => get_post_meta($attachment->ID, '_wp_attachment_image_alt', true),
        'caption' => $attachment->post_excerpt,
        'description' => $attachment->post_content,
        'href' => get_permalink($attachment->ID),
        'src' => $attachment->guid,
        'title' => $attachment->post_title
    );
}

/**
 * Custom Filter for Gallery Image Captions
 */
function my_gallery_image_caption($attachment_id, $captiontag, $selector, $itemtag) {

    $id = $attachment_id;

    $my_image_meta = get_image_meta($id);
    
    // Here's where to customise the caption content.
    // This example uses the meta title and caption. You can display any value
    // from the $my_image_meta array. You can add your own HTML too.
    return "<{$captiontag} class='wp-caption-text gallery-caption' id='{$selector}-{$id}'>
    Image Title: ". $my_image_meta['title'] . "<br>Image Caption: ". $my_image_meta['caption'] . "</{$captiontag}></{$itemtag}>";

}
add_filter('gallery_image_caption', 'my_gallery_image_caption', 10, 4);

custom_image_caption_filter_hook_media.php

<?php

		/**
		 * Custom Gallery Image Caption Filter
		 * 
		 * I want to use any of the media
		 * attachment meta that's available. In
		 * this example, we'll use the image title
		 * and caption values for the gallery caption.
		 * 
		 * $id is the attachment ID (i.e., media file).
		 *
		 * ~mlc 16 February 2020
		 */
		$filtered_caption = 
			apply_filters( 'gallery_image_caption', $id, $captiontag, $selector, $itemtag );

		// Custom: If filtered then use the new content.
		if ( ! empty( $filtered_caption ) ) {
			$output .= $filtered_caption;

		// Custom: Else use the default WordPress caption logic.
		} else {

			if ( $captiontag && trim( $attachment->post_excerpt ) ) {
				$output .= "
					<{$captiontag} class='wp-caption-text gallery-caption' id='$selector-$id'>" . wptexturize( $attachment->post_excerpt ) . "
					</{$captiontag}>";
			}

			$output .= "</{$itemtag}>";

		} // Custom: else

Screen Capture of the Results

Gallery with the media attachment title and caption displayed using default formatting.

[gallery size="medium" columns="2" link="file" ids="68,75"]

---

Gallery with the media attachment title, caption, and description using a styled H4 captiontag .

[gallery size="large" columns="3" link="file" ids="29,30,31" captiontag="h4"]

Example Media Attachment Meta for Above Gallery

---

Gallery Image Caption with links to the image file and the media attachment.

Filter Used for Above Example

    return "<{$captiontag} class='wp-caption-text gallery-caption' id='{$selector}-{$id}'>" .
            "Title: " . $my_image_meta['title'] . "<br>" .
            "Caption: " . $my_image_meta['caption'] . "<br>" . 
            "Description: ". $my_image_meta['description'] . "<br>" .
            "<a href='" . $my_image_meta['src'] . "'>Download Image</a><br>" .
            "<a href='" . $my_image_meta['href'] . "'>View Attachment</a><br>" .
        "</{$captiontag}></{$itemtag}>";

Now Available as a Plugin!

I'm excited to announce the release of the official Gallery Image Captions (GIC) plugin!

GIC is a minimalist low footprint plugin that created the gallery shortcut override for you. All you have to do after activating GIC is write your filter.

If you decide to use the GIC plugin, I'd appreciate your feedback. Either post to the support forum or write a review.