[wp-trac] [WordPress Trac] #11157: Add sidebar descriptions to sidebar settings and widget admin screen

[WordPress Trac]

#11157: Add sidebar descriptions to sidebar settings and widget admin screen
--------------------------+-------------------------------------------------
 Reporter:  jeremyclarke  |       Owner:  jeremyclarke
     Type:  enhancement   |      Status:  new         
 Priority:  normal        |   Milestone:  2.9         
Component:  Widgets       |     Version:  2.9         
 Severity:  normal        |    Keywords:  has-patch   
--------------------------+-------------------------------------------------
 == 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}}}

-- 
Ticket URL: <http://core.trac.wordpress.org/ticket/11157>
WordPress Trac <http://core.trac.wordpress.org/>
WordPress blogging software