Display caption with the_post_thumbnail

[hd-J]

It seems to me that there could be room for improvement with the_post_thumbnail function. So far, I did not find any way to display the caption below the thumbnail, like we do today with "normal" images.

What do you think of the idea of adding an argument for displaying caption text with the thumbnail?

[mikeschinkel]

+1

[GlobalChange]

Old Ticket wondering where we are with this? This is an important function to ensure that wordpress users comply with copy right laws and provide sources for photos in captions for featured images.
Thank you

Replying to hd-J:

It seems to me that there could be room for improvement with the_post_thumbnail function. So far, I did not find any way to display the caption below the thumbnail, like we do today with "normal" images.

What do you think of the idea of adding an argument for displaying caption text with the thumbnail?

[johnbillion]

For what it's worth, it's fairly simple to add a function to your theme to get the thumbnail caption:

function get_post_thumbnail_caption() {
	if ( $thumb = get_post_thumbnail_id() )
		return get_post( $thumb )->post_excerpt;
}

Then you can just do something along the lines of:

if ( has_post_thumbnail() ) {
	the_post_thumbnail( 'medium' );
	echo wpautop( get_post_thumbnail_caption() );
}

[GlobalChange]

HI Added the code you suggested above and nothing happened. I attached my php code from the appearance editor for both the Featured.php and Function.php. Sorry I don't know much about coding. Can you include the code in the attached docs and reattach? Thank you very much and Warm Regards,

[globalchange]

Hi I actually already downloaded version 3.3.1 however, I guess these php functions did not update or change when I updated my version from the updates panel. So it says that I am using the latest version and I am utilizing all the new features and taking advantage of the updated security features but, for some reason it's not reflected in the attached files.
Thank you
Kind Regards

[dd32]

The version field is used to indicate the first version in which a problem was identified in, or reproduced in.

[GlobalChange]

High What are next steps? Thank you

[globalchange]

Replying to GlobalChange:

Hi What are next steps? Thank you

Hi am wondering what the next step would be. Thank you

[Zahak]

So is this feature request dead? Or is it something that will come?

[SergeyBiryukov]

Replying to Zahak:

So is this feature request dead? Or is it something that will come?

It needs a patch to be considered. However, there's a simple workaround mentioned in comment:5.

[johnbillion]

I don't believe there's need for a new argument for this function at all. You have much more control over the output by outputting the caption yourself in your template file. Should we add arguments for every field? (caption, title, description).

We could probably add some new template tags to help with this (I have some that I use in my theme framework) but extra arguments for the_post_thumbnail() isn't the way to go.

[farkas.aj]

Replying to johnbillion:

I don't believe there's need for a new argument for this function at all… Should we add arguments for every field? (caption, title, description).

This is essential. As someone who's made my living creating images, we need a lower bar for captioning images. If someone is going to steal my work and post it on this site without compensating me, the least WP can do is make it easy for them to give me attribution.

[MikeSchinkel]

Replying to johnbillion:

Should we add arguments for every field? (caption, title, description).

Yes.

[krogsgard]

We could probably add some new template tags to help with this (I have some that I use in my theme framework) but extra arguments for the_post_thumbnail() isn't the way to go.

I would say this topic is as necessary as ever. Featured images have tremendous adoption, of course, and both captions and image sourcing are common and often necessary.

I'd love to see some template tags to help make captions for featured images a much simpler task for themers, and it would allow the theme team to define some good practices for showcasing additional featured image data in themes.

[flixos90]

Replying to johnbillion:

I don't believe there's need for a new argument for this function at all. You have much more control over the output by outputting the caption yourself in your template file. Should we add arguments for every field? (caption, title, description).

We could probably add some new template tags to help with this (I have some that I use in my theme framework) but extra arguments for the_post_thumbnail() isn't the way to go.

I agree with this approach. Showing the featured image caption is a very specific need which should not be supported directly by the_post_thumbnail(), other image functions do not include a caption either.

However a new template tag for this could be valuable. Maybe we should first add a general function like wp_get_image_caption() to get the caption for an image, outsourcing code from the img_caption_shortcode() function (for the wp_caption shortcode) and calling the function from there instead. We could then use that new function by a possible get_post_thumbnail_caption().

[flixos90]

12235.diff​ adds an easy-to-use function to get the caption for a specific attachment, wp_get_attachment_caption(). It furthermore adds functions to get the caption for the featured image of a post, using the new attachment caption function.

This makes it easy to display the caption of the featured image in a theme if desired. While the caption shouldn't be part of the featured image function itself as it would be too specific, the functions added by this patch make it easy for a theme developer to include it.

[joemcgill]

Replying to flixos90:

12235.diff​ adds an easy-to-use function to get the caption for a specific attachment, wp_get_attachment_caption(). It furthermore adds functions to get the caption for the featured image of a post, using the new attachment caption function.

I agree with this approach and 12235.diff​ looks great to me. +1

[flixos90]

12235.2.diff​ adds unit tests. This should be good to go in now.

[joemcgill]

@flixos90 The tests look good. My only suggestion is that we probably don't need to test the process of setting the caption in test_wp_get_attachment_caption() and test_get_the_post_thumbnail_caption(), and instead should focus on whether the output is what we expect based on the attachment's excerpt value, like you did with test_the_post_thumbnail_caption().

If the goal there is to test whether an attachment with a blank excerpt value will return false, we should do that in a separate test like test_wp_get_attachment_caption_empty() rather than mixing two cases in single tests. If you had something else in mind, feel free to clarify.

[flixos90]

Replying to joemcgill:

If the goal there is to test whether an attachment with a blank excerpt value will return false, we should do that in a separate test like test_wp_get_attachment_caption_empty() rather than mixing two cases in single tests. If you had something else in mind, feel free to clarify.

You're right, that's what I intended to do. Splitting up the tests definitely makes sense, so I did that in 12235.3.diff​.

[flixos90]

12235.4.diff​ replaces the esc_html() call with wp_kses(). Captions may include HTML, and the caption should be handled similar like in the wp_caption shortcode.

[joemcgill]

I think we're really close, but after getting some feedback from a few other developers, I wanted to suggest a few additional changes before this goes in.

First, when the caption is left blank, @boonebgorges suggested that we should probably return an empty string rather than returning false and I tend to agree. I assume you were following the lead of wp_get_attachment_url() there, but I think in this case, we don’t need to be as strict.

Second, @ocean90 suggested that we really don’t need to use wp_kses() on the_post_thumbnail_caption() because it’s essentially the same as the_excerpt() in this context, rather than in img_caption_shortcode() where we're parsing post data inserted into a shortcode.

That said, we should also run some of the text formatting filters that automatically run on the_excerpt(). I’m thinking wptexturize(), convert_smilies(), and convert_chars(). I’m 50/50 on whether we should leave off wpautop(). The input we accept is a multi-line textarea, but the current behavior of captions generated by the shortcode is to not automatically convert to paragraphs, so I lean towards leaving off for consistency there. We can always reevaluate that decision if we want to automatically convert breaks to paragraphs in captions later, as well.

12235.5.diff​ returns an empty string when the caption is left blank and updates the tests to account for the change. This also removes the wp_kses() call from the_post_thumbnail_caption() and adds the new filters to wp-includes/default-filters.php.

[joemcgill]

12235.6.diff​ is a followup to 12235.5.diff​ that actually removes the wp_kses() call from the_post_thumbnail_caption() and adds the new filter that was intended to be used in the_post_thumbnail_caption().

[joemcgill]

12235.7.diff​ includes some additional cleanup. Since we are using get_the_post_thumbnail_caption() to retrieve the caption string, we should treat it like get_the_excerpt() and always return a string instead of false.

[joemcgill]

In 37915:

Post Thumbnails: Add helper functions for attachment captions.

This adds three new functions for getting/displaying attachment captions:

• wp_get_attachment_caption - Retrieves a caption for a specific attachment.
• get_the_post_thumbnail_caption() - Returns the post thumbnail caption.
• the_post_thumbnail_caption() - Displays the post thumbnail caption.

These are helpful for displaying a caption associated with an image directly
in a template, rather than using the caption shortcode.

This also introduces two new filters:

• wp_get_attachment_caption - Filters the value of wp_get_attachment_caption().
• the_post_thumbnail_caption - Filters the display of the post thumbnail caption.

the_post_thumbnail_caption() is automatically filtered by wptexturize(),
convert_smilies(), and convert_chars() in wp-includes/default-filters.php.

Props flixos90, joemcgill.
Fixes #12235.