id	summary	reporter	owner	description	type	status	priority	milestone	component	version	severity	resolution	keywords	cc
11157	Add sidebar descriptions to sidebar settings and widget admin screen	jeremyclarke	azaozz	"== Justification ==

The value of descriptions for widgets is obvious. It's a loved feature that everyone takes for granted when creating widgets. The same principle applies equally to widget sidebars. In complex themes with lots of sidebars it becomes very challenging to keep track of what each sidebar is for and where it is likely to display. Giving users information inside the widgets screen is likely to avoid the need for external reference materials about sidebars entirely, and as the descriptions can be dynamically generated during sidebar definition the possibilities are endless.

Currently the only way to handle this issue is to give the sidebars long-winded names that effectively incorporate descriptions. This should be changed and the included patch is totally logical given the API as it already exists. 

== Solution ==
This patch adds a 'description' parameter that can be passed into the {{{register_sidebar()}}} function along with name and id, and which is then shown in the widget administration screen inside the sidebar container. To test the patch add 'description' to any sidebar definition, like this:

{{{
if ( function_exists('register_sidebar') ) {
	register_sidebar(array(
		'name' => 'Complex Sidebar',
		'id' => 'complex',
		'description' => 'Here is some important considerations about Complex Sidebar',
		'before_widget' => '<li id=""%1$s"" class=""widget %2$s"">',
		'after_widget' => '</li>',
		'before_title' => '<h2 class=""widgettitle"">',
		'after_title' => '</h2>',
	));
}
}}}

It looks like this 

[[Image(http://simianuprising.com/wp-content/uploads/2009/11/Screen-shot-2009-11-16-at-8.27.59-PM.png)]]


== Implementation Details ==
=== Adding 'description' as a sidebar setting ===
	* I added it as an empty string to the default sidebar definitions in a /wp-includes/widgets.php and /wp-admin/widgets.php, the two places where the expected contents of a widget registration are listed (to my knowledge and searching).
	* The existing system deals with the new array element with no issues.

=== Displaying the description in the widget configuration screen (modeled on widget descriptions) === 
	* I added a function {{{wp_sidebar_description( $id )}}} that was copied and modified from the matching {{{wp_widget_description( $id )}}} function in /wp-includes/widgets.php
	* IMHO the function would make more sense as {{{get_widget_description( $id )}}} but I opted for consistency to help smooth the process instead. 
	* I then add  {{{wp_sidebar_description( $id )}}} to the definition of  {{{wp_list_widget_controls()}}} in /wp-admin/includes/widgets.php, the function which lists all widgets for a given sidebar in the admin screen (I also added a short phpdoc description for the function that was missing). The description echo is wrapped in an if statement to make sure it exists and is inside a {{{<p class=""description"">}}} inside a {{{<div class=""sidebar-description"">}}}. The class='description' is a general css style to make it italic and grey (like the text at the top of the pool of unused widgets on the left side of the screen). 
	* For CSS I added the description div, as {{{.widget-liquid-right .sidebar-description}}} to an existing css definition in /wp-admin/css/widgets.dev.css and wp-admin/css/widgets.css that was already being aplied to the individual widget boxes in the sidebar container to give them a set width and padding. I also added a definition just for {{{.widget-liquid-right .sidebar-description}}} to both files to only have 10px of margin-bottom for the description, which I think makes it look perfectly balanced inside the container (the individual widgets each have 20px bottom margin and no top margin).
	
	
== Pre-Emptive +1s ==
This came up on the wp-hackers list and so far several people have said they like the idea:

{{{""+1 for this. I'd definitely use this to help my clients understand how to use, edit, and customize their sites. For now, in some cases I've resorted to putting descriptive titles (that are hidden by css on the front) to try and make it easier for them. Clients still tend to get embarrassed by having to ask, and its not pleasant for me too realize I've not made it easy enough."" -Ken Newman}}}

{{{""+50"" -Doug Stewart}}}

	

	"	enhancement	closed	normal	2.9	Widgets		normal	fixed	has-patch tested commit	jeremyclarke