Allow filtering of the final HTML output of media related shortcodes

[gnotaras]

Sometimes it is required to further process the final HTML output of the media related shortcodes, eg caption or gallery, so as to add extra HTML code such as enclosing div or span elements or just modify the existing HTML code during run time.

For instance the final output of img_caption_shortcode could be filtered:

https://core.trac.wordpress.org/browser/tags/4.4.2/src/wp-includes/media.php#L1537

Passing all relevant image attachment data, like ID and size, would also be very useful.

I hope that I am not missing anything but right now the only way to insert code inside the <figure> or <figcaption> block seems to be the complete override of the img_caption_shortcode function.

[SergeyBiryukov]

Related: #14130, #20230, #29832.

[mlchaves]

Hello,

I created a filter to allow caption customisation. Here's the Gist.

​https://gist.github.com/marklchaves/1116bba6fcd9688b4df5b121d5d76277

This Gist has two screen grabs.

1. Gallery with the media attachment title and caption displayed using default formatting.
2. Gallery with the media attachment title, caption, and description using a styled H4 captiontag .

I'd like to submit a pull request if you feel this is worthy.

Thanks for your time!

[mlchaves]

Update

I developed the Gallery Image Captions (GIC) plugin that allows caption customisations.

With GIC, you can write a filter to modify, style, and even add attachment meta to the WordPress gallery caption.

​https://wordpress.org/plugins/gallery-image-captions/

[sahilgidwani]

Hi @gnotaras ,

You can use existing WordPress filters to modify the output without overriding the entire function. The two key filters you need to use are:

1. img_caption_shortcode – Filters the output of the caption shortcode.
2. post_gallery – Filters the output of the gallery shortcode.

Example: Modifying the Caption Shortcode Output

To wrap <figure> with an extra <div class="custom-wrapper">:

<?php
add_filter('img_caption_shortcode', function ($output, $attr, $content) {
    if ($output !== '') {
        return $output;
    }

    // Generate the default caption HTML
    $caption_id = isset($attr['caption_id']) ? ' id="' . esc_attr($attr['caption_id']) . '"' : '';
    $class      = 'wp-caption ' . esc_attr($attr['align'] ?? '') . ' ' . esc_attr($attr['class'] ?? '');
    $caption    = esc_html($attr['caption'] ?? '');

    $html = '<div class="custom-wrapper">';
    $html .= sprintf(
        '<figure class="%s">%s<figcaption%s>%s</figcaption></figure>',
        $class,
        do_shortcode($content),
        $caption_id,
        $caption
    );
    $html .= '</div>';

    return $html;
}, 10, 3);

Example: Modifying the Gallery Shortcode Output

To wrap the gallery with <section class="custom-gallery">:

<?php
add_filter('post_gallery', function ($output, $attr, $instance) {
    $output = '<section class="custom-gallery">' . gallery_shortcode($attr) . '</section>';
    return $output;
}, 10, 3);

This way, you avoid overriding core functions and can customize media-related shortcodes dynamically.