WordPress.org

Make WordPress Core

Opened 10 years ago

Closed 3 years ago

#12235 closed enhancement (fixed)

Display caption with the_post_thumbnail

Reported by: hd-J Owned by: flixos90
Milestone: 4.6 Priority: normal
Severity: normal Version: 2.9
Component: Post Thumbnails Keywords: has-patch has-unit-tests commit
Focuses: Cc:
PR Number:

Description

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?

Attachments (9)

Original Featured php.doc (30.5 KB) - added by GlobalChange 8 years ago.
Original Function php.doc (47.5 KB) - added by GlobalChange 8 years ago.
12235.diff (2.2 KB) - added by flixos90 3 years ago.
12235.2.diff (5.1 KB) - added by flixos90 3 years ago.
12235.3.diff (5.6 KB) - added by flixos90 3 years ago.
12235.4.diff (5.6 KB) - added by flixos90 3 years ago.
12235.5.diff (6.3 KB) - added by joemcgill 3 years ago.
12235.6.diff (6.5 KB) - added by joemcgill 3 years ago.
12235.7.diff (6.4 KB) - added by joemcgill 3 years ago.

Download all attachments as: .zip

Change History (42)

#1 @mikeschinkel
10 years ago

  • Cc mikeschinkel@… added

+1

#2 @nacin
10 years ago

  • Component changed from Embeds to Post Thumbnails
  • Milestone changed from Unassigned to 3.1

#3 @nacin
9 years ago

  • Milestone changed from Awaiting Triage to Future Release

#4 in reply to: ↑ description @GlobalChange
8 years ago

  • Cc GlobalChange added
  • Keywords changed from the_post_thumbnail, caption, wp-caption-text to the_post_thumbnail caption wp-caption-text
  • Severity changed from minor to normal
  • Version set to 3.3.1

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?

#5 @johnbillion
8 years ago

  • Keywords the_post_thumbnail caption wp-caption-text removed

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() );
}

#6 @GlobalChange
8 years ago

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,

#7 @SergeyBiryukov
8 years ago

  • Version changed from 3.3.1 to 2.9

#8 @globalchange
8 years ago

  • Version changed from 2.9 to 3.3.1

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

#9 @dd32
8 years ago

  • Version changed from 3.3.1 to 2.9

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

#10 follow-up: @GlobalChange
8 years ago

High What are next steps? Thank you

#11 in reply to: ↑ 10 @globalchange
8 years ago

Replying to GlobalChange:

Hi What are next steps? Thank you

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

#12 @DrewAPicture
8 years ago

  • Cc xoodrew@… added

#13 follow-up: @Zahak
6 years ago

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

#14 in reply to: ↑ 13 @SergeyBiryukov
6 years ago

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.

#15 follow-ups: @johnbillion
6 years ago

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.

#16 in reply to: ↑ 15 @farkas.aj
5 years ago

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.

#17 in reply to: ↑ 15 @MikeSchinkel
5 years ago

Replying to johnbillion:

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

Yes.

This ticket was mentioned in Slack in #core by helen. View the logs.


4 years ago

#19 @krogsgard
4 years ago

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.

#20 in reply to: ↑ 15 @flixos90
4 years ago

  • Keywords needs-patch added

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
3 years ago

#21 follow-up: @flixos90
3 years ago

  • Keywords has-patch needs-unit-tests added; needs-patch removed
  • Milestone changed from Future Release to 4.6
  • Type changed from feature request to enhancement

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.

#22 @flixos90
3 years ago

  • Owner set to flixos90
  • Status changed from new to accepted

#23 @flixos90
3 years ago

  • Status changed from accepted to assigned

#24 in reply to: ↑ 21 @joemcgill
3 years ago

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
3 years ago

#25 @flixos90
3 years ago

  • Keywords has-unit-tests commit added; needs-unit-tests removed

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

#26 follow-up: @joemcgill
3 years ago

@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
3 years ago

#27 in reply to: ↑ 26 @flixos90
3 years ago

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.

This ticket was mentioned in Slack in #core by ocean90. View the logs.


3 years ago

@flixos90
3 years ago

#29 @flixos90
3 years ago

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
3 years ago

#30 @joemcgill
3 years ago

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
3 years ago

#31 @joemcgill
3 years ago

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().

#32 @joemcgill
3 years ago

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
3 years ago

#33 @joemcgill
3 years ago

  • Resolution set to fixed
  • Status changed from assigned to closed

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.

Note: See TracTickets for help on using tickets.