Add sidebar descriptions to sidebar settings and widget admin screen, props jeremyclarke scribu, fixes #11157

git-svn-id: https://develop.svn.wordpress.org/trunk@12213 602fd350-edb4-49c9-b593-d223f7449a82

wp-admin/css/widgets.dev.css

@@ -28,12 +28,17 @@ div.widget-liquid-right {
 }
 
 .widget-liquid-right .widget,
-#wp_inactive_widgets .widget {
+#wp_inactive_widgets .widget,
+.widget-liquid-right .sidebar-description {
 	width: 250px;
 	margin: 0 auto 20px;
 	overflow: hidden;
 }
 
+.widget-liquid-right .sidebar-description {
+	margin-bottom: 10px;
+}
+
 #wp_inactive_widgets .widget {
 	margin: 0 10px 20px;
 	float: left;

wp-admin/includes/widgets.php

@@ -52,18 +52,28 @@ function wp_list_widgets() {
 }
 
 /**
- * {@internal Missing Short Description}}
+ * Show the widgets and their settings for a sidebar.
+ * Used in the the admin widget config screen.
  *
  * @since unknown
  *
- * @param string $sidebar
+ * @param string $sidebar id slug of the sidebar
  */
 function wp_list_widget_controls( $sidebar ) {
 	add_filter( 'dynamic_sidebar_params', 'wp_list_widget_controls_dynamic_sidebar' );
 
-	echo "\t<div id='$sidebar' class='widgets-sortables'>\n";
+	echo "<div id='$sidebar' class='widgets-sortables'>\n";
+
+	$description = wp_sidebar_description( $sidebar );
+
+	if ( !empty( $description ) ) {
+		echo "<div class='sidebar-description'>\n";
+		echo "\t<p class='description'>$description</p>"; 
+		echo "</div>\n";
+	}
+
 	dynamic_sidebar( $sidebar );
-	echo "\t</div>\n";
+	echo "</div>\n";
 }
 
 /**

wp-admin/widgets.php

@@ -37,6 +37,7 @@ $parent_file = 'themes.php';
 register_sidebar(array(
 	'name' => __('Inactive Widgets'),
 	'id' => 'wp_inactive_widgets',
+	'description' => '',
 	'before_widget' => '',
 	'after_widget' => '',
 	'before_title' => '',

wp-includes/script-loader.php

@@ -434,7 +434,7 @@ function wp_default_styles( &$styles ) {
 
 	$styles->add( 'global', "/wp-admin/css/global$suffix.css", array(), '20090630' );
 	$styles->add( 'media', "/wp-admin/css/media$suffix.css", array(), '20091029' );
-	$styles->add( 'widgets', "/wp-admin/css/widgets$suffix.css", array(), '20090603' );
+	$styles->add( 'widgets', "/wp-admin/css/widgets$suffix.css", array(), '20091118' );
 	$styles->add( 'dashboard', "/wp-admin/css/dashboard$suffix.css", array(), '20090514' );
 	$styles->add( 'install', "/wp-admin/css/install$suffix.css", array(), '20090514' );
 	$styles->add( 'theme-editor', "/wp-admin/css/theme-editor$suffix.css", array(), '20090625' );

wp-includes/widgets.php

@@ -544,6 +544,7 @@ function register_sidebar($args = array()) {
 	$defaults = array(
 		'name' => sprintf(__('Sidebar %d'), $i ),
 		'id' => "sidebar-$i",
+		'description' => '',
 		'before_widget' => '<li id="%1$s" class="widget %2$s">',
 		'after_widget' => "</li>\n",
 		'before_title' => '<h2 class="widgettitle">',
@@ -650,6 +651,28 @@ function wp_widget_description( $id ) {
 		return esc_html( $wp_registered_widgets[$id]['description'] );
 }
 
+/**
+ * Retrieve description for a sidebar.
+ *
+ * When registering sidebars a 'description' parameter can be included that
+ * describes the sidebar for display on the widget administration panel.
+ *
+ * @since 2.9.0
+ *
+ * @param int|string $id sidebar ID.
+ * @return string Sidebar description, if available. Null on failure to retrieve description.
+ */
+function wp_sidebar_description( $id ) {
+	if ( !is_scalar($id) )
+		return;
+
+	global $wp_registered_sidebars;
+
+	if ( isset($wp_registered_sidebars[$id]['description']) )
+		return esc_html( $wp_registered_sidebars[$id]['description'] );
+}
+
+
 /**
  * Remove widget from sidebar.
  *