[Post Featured Image]: add option to display image caption/credit

[samiff]

What problem does this address?

When using a block theme that leverages wp:post-featured-image to display a post's featured image, there is no caption being rendered by that block, nor is there an option to do so.

Jetpack for example offers external media providers like Openverse and Pexels that users can select from when setting a featured image. Generally, the Caption field is used to credit the source, and you'll see that themes like Twenty Twenty will render the caption/credit for featured images by default.

Concern originally raised in: Automattic/jetpack#23408

What is your proposed solution?

Given the fluid discussion in: #27617

I'm not quite sure at this point, but I think it'd be nice to have an option that would show the caption/credit for the featured image - especially when the images are sourced from a third-party. At bare minimum, at least have the figcaption output in the HTML even if it's not visually displayed.

[kaffeeringe]

I can't use Gutenberg themes, until it displays the description caption. I stored all the copyright notices there.

[hagege]

That would indeed be a nice option, e.g. by ticking in the properties whether that should be shown.

[carolinan]

@kaffeeringe even in classic PHP based themes, displaying the description is a custom solution.
Chances are that this field will never be supported by the block by default. You may want to consider moving the data to another field in your database, like the caption.

[carolinan]

I learnt that none of the media captions use the caption text from the media library.
So if we want the caption to use the media library data by default, they all need to be updated, not only the post featured image block.

I want to read up on the history and why this choice was made.
It is probably because the same media can be used in multiple places and one caption may not be enough because it is situational. But it has that side effect that existing data is not easily available.

[kaffeeringe]

@carolinan Sorry, I mixed up the fields. I use Wordpress in German and there caption and description are called "Beschriftung" and "Beschreibung" and I always mix them up. I use the caption field with my images.

It would be nice if the caption was only the suggested caption if you use an image in a block or as featured image. So you can reuse an image with different captions.

[carolinan]

It could be used as a pre-filled placeholder, interesting idea.

[greening]

I'm refactoring a couple of websites into FSE, and I really wish this was available in the Featured Image block. (I don't need it for copyright declarations, but sure would like it for traditional captions.

[jethin]

Greetings,

I agree that the ability to show captions on featured images should be rolled into WP. Until then, I came up with the following workaround:

Set up a block variation. "For now, let’s create variations.js and put the file in our theme’s assets/js folder":

wp.blocks.registerBlockVariation(
    'core/post-featured-image',
    {
        name: 'sotp_post_featured_image',
        title: 'Post Featured Image + Caption',
        description: 'Displays the post\'s featured image with caption.',
        isActive: [ 'namespace' ],
        attributes: {
            namespace: 'sotp_post_featured_image',
            className: 'sotp-post-featured-image'
        },
        scope: [ 'inserter' ]
    }
);

"Next, you need to enqueue variations.js... This code should generally be placed in your theme’s functions.php..."

function example_enqueue_block_variations() {
	wp_enqueue_script(
		'example-enqueue-block-variations',
		get_template_directory_uri() . '/assets/js/variations.js',
		array( 'wp-blocks', 'wp-dom-ready' ),
		wp_get_theme()->get( 'Version' ),
		false
	);
}
add_action( 'enqueue_block_editor_assets', 'example_enqueue_block_variations' );

And finally filter the block render (functions.php):

function include_feature_image_caption($block_content, $block){
    if ( isset($block['attrs']['className']) && $block['attrs']['className'] === 'sotp-post-featured-image') {
        $caption = '<figcaption class="wp-element-caption">' . get_the_post_thumbnail_caption() . '</figcaption>';
        $block_content = str_replace('</figure>', $caption . '</figure>', $block_content);
    }
    return $block_content;
}
add_filter( 'render_block_core/post-featured-image', 'include_feature_image_caption', 10, 2 );

I make no guarantees for this code. Hope it helps someone.

[updated enqueuing as per @janvitos comment below.]

[janvitos]

Hope it helps someone

Works like a charm, thanks @jethin!

Just one thing: How do you register your block variation? Using PHP?

I did it this way, but I'm not sure it's the "proper way":

add_action( 'enqueue_block_editor_assets', function() {
    wp_enqueue_script( 'prefix-block-variations', THEME_JS_URL . 'block-variations.js', array( 'wp-blocks' ) );
});

[kevinpoot]

IMO this should definitely be included inside the block with an option to disable (or enable) it. Any update on this being implemented anytime soon?