Add 'description' setting for thumbnails/featured image and show that text in metabox

[jeremyclarke]

Problem: Featured Image Metabox is Confusing

Currently the featured image metabox is very sparse and does not explain what will happen with the image at all. This can be confusing for users who didn't create their own theme, especially if multiple image sizes will be used and created, since they only see one size and might not check all parts of the theme after publishing.

This is relevant both to simple sites where the admin is installing 3rd party themes they are unfamiliar with and enterprise sites with lots of users who haven't necessarily been trained to know exactly what the featured images will be used for.

Solution: Let themers display a description

Somewhere in the images/thumbnails API themers need the ability to add a description of how featured images are used in the theme so that this text can be shown in the Featured Image metabox. That way they could explain complex situations (or simple ones).

Examples:

• The featured image will be shown on archives next to the optional excerpt of posts.

• 3 different sizes of featured image will be used: 50px - shown next to the post title in sidebar headlines. 150px - shown next to post excerpts on the homepage and archives. 500px - shown in the slider on the homepage.

And of course, for our favorite new theme, twentyten:

• This image will be used in the header of the site behind the site title when viewing this article.

Allowing these labels will give themers as much flexibility as they need for explaining the system within the UI and will sidestep a lot of other issues with the thumbnails system and its lack of communication about thumbnail sizes and uses. I think almost any scenario could be summarized here and in almost any non-standard scenario having this text available will have a positive effect on thumbnail quality.

This situation is very similar to #11157 which added descriptions to sidebars. When these APIs are used on complex sites the developers need a chance to communicate directly with users to explain how the data entered will behave.

Technical solution

I'm not sure what they best way to do this technically would be. The featured images system isn't well set up to handle metadata like this unfortunately. Ideally it would accept sets of parameters the way register_sidebar() does, but add_image_size() instead uses straight up arguments.

If nothing else the simplest solution might be to add a new function that applies globally to the post thumbnail system, something like

set_post_thumbnail_description($text);

Alternately we could add another argument to set_post_thumbnail_size:

set_post_thumbnail_size( $width, $height, $description );

Ideally the label and all other metadata should be set using the main call that turns on the feature, add_theme_support(), but that function is pretty basic and has no intelligence about the features themselves. Not sure why the thumbnails system is set up this way at all rather than having the on/off switch be the same as the function used to define how the feature will actually work.

The naming for this solution is frustrated by the more general situation of naming for 'Featured Images', who's label was changed without any changes to the function names, as discussed in #12554. IMHO an overhaul of the entire API is in order that would incorporate this ticket and solve other problems in the process.

Interim Solution Until this is implemented

If you want this effect without waiting for the api to change it can be done very easily with a couple lines of jQuery to insert the text in the metabox. This solution is or course not futureproof. Add the following in the admin somewhere (like admin_footer action hook:

jQuery(document).ready(function($) {
	$('#postimagediv .inside').prepend('<p>DESCRIPTION TEXT</p>');
});

[DrewAPicture]

Seems like this could be a common-sense enhancement for the featured image metabox -- especially if you take it in the same vein as #11157 where a description argument was added to register_sidebar().

That said, this seems quite edge-case, as, unlike sidebars, there's only one featured image metabox. Also, it's currently possible to simply inject your own description by prepending content via the admin_post_thumbnail_html filter added in 2.9.

[flixos90]

Replying to DrewAPicture:

That said, this seems quite edge-case, as, unlike sidebars, there's only one featured image metabox. Also, it's currently possible to simply inject your own description by prepending content via the admin_post_thumbnail_html filter added in 2.9.

I agree that having this filter should be sufficient for this cause. A custom description inside the Featured Image metabox could easily bloat up the metabox, so I don't think we should encourage it by adding an additional parameter to set_post_thumbnail_size() or by doing something like add_theme_support( 'post-thumbnails-description' ) (any theme author can still use the above filter if they wanted to add a descriptive text).

However, we might think about inserting an additional paragraph into the "Help" tab of the post editor (only for post types with featured image support) to describe what a featured image is.

[jeremyclarke]

This gist has a demo of how to use WP's admin_post_thumbnail_html filter to insert content in featured image metabox. Posting here because someone found me on twitter to ask about the solution and figured anyone else stumbling here would find this useful too:

[EDIT -- UPDATED URL (prev. had 'jeremyclarke' as username]
​https://gist.github.com/jerclarke/faa6a9da4b0dfe5c524016b40b67a164

Contains a bunch of notes about nuances of this filter, which is a bit unpredictable.

[joyously]

Replying to flixos90:

I agree that having this filter should be sufficient for this cause. A custom description inside the Featured Image metabox could easily bloat up the metabox, so I don't think we should encourage it by adding an additional parameter to set_post_thumbnail_size() or by doing something like add_theme_support( 'post-thumbnails-description' ) (any theme author can still use the above filter if they wanted to add a descriptive text).

However, we might think about inserting an additional paragraph into the "Help" tab of the post editor (only for post types with featured image support) to describe what a featured image is.

This filter works fine for the meta box. (I have used it on 2 themes.) Not sure how metaboxes will be with Gutenberg, though.
I don't quite see how to generically put a description in the Help tab for featured images, because they are different for every theme.
(I tried to see what was in the gist mentioned, but it is 404.)

[jeremyclarke]

Replying to joyously:

(I tried to see what was in the gist mentioned, but it is 404.)

Sorry, I changed my Github username, new URL (and I'll update the one above) is ​https://gist.github.com/jerclarke/faa6a9da4b0dfe5c524016b40b67a164

[jaymanpandya]

Moving this implementation to Gutenberg as the old Featured Metabox is no longer used in Gutenberg. Link to issue on git repo of Gutenberg ​https://github.com/WordPress/gutenberg/issues/12742