id	summary	reporter	owner	description	type	status	priority	milestone	component	version	severity	resolution	keywords	cc
13522	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 ==

[[Image(http://simianuprising.com/wp-content/uploads/2010/05/wp-trac-featured-image-description.png)]]

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

"	enhancement	new	normal	Future Release	Post Thumbnails		normal			jeremyclarke jane