Add sidebar descriptions to sidebar settings and widget admin screen

[jeremyclarke]

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

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

[jeremyclarke]

patch to add sidebar descriptions to widgets api and display them on widgets admin screen. against revision 12195

[scribu]

avoid calling wp_sidebar_description() twice

[scribu]

Pretty sweet. I've added a slight improvement to your patch. Hope you don't mind. :)

[jeremyclarke]

Ha cool, thanks :)

[azaozz]

Looks good. The description is only used on the widgets admin page, shall we add it directly in wp_list_widget_controls() or maybe move wp_sidebar_description() to wp-admin/includes/widgets.php.

[jeremyclarke]

I did it that way to be the same as wp_widget_description(), which is also why I put it in that file (its right below).

IMHO its worth having it as its own function, an example use would be to display the description in a theme when a sidebar is missing, rather than having default content:

if (!dynamic_sidebar('complex') {
     echo "<div class="widget">";
     wp_sidebar_description(); 
     echo "</div> \n";
}

[azaozz]

(In [12213]) Add sidebar descriptions to sidebar settings and widget admin screen, props jeremyclarke scribu, fixes #11157