Support descriptions for individual customizer controls.

* Control title (label) markup will also only be output if specified.
* Control section descriptions are no longer italicized for visual hierarchy / differentiation.

props celloexpressions. fixes #27981.

Built from https://develop.svn.wordpress.org/trunk@28927


git-svn-id: http://core.svn.wordpress.org/trunk@28725 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-admin/css/customize-controls-rtl.css

@@ -275,6 +275,10 @@ body {
 	line-height: 24px;
 }
 
+p.customize-section-description {
+	font-style: normal;
+}
+
 .customize-control {
 	width: 100%;
 	float: right;
@@ -314,6 +318,13 @@ body {
 	margin-bottom: 5px;
 }
 
+.customize-control-description {
+	display: block;
+	font-style: italic;
+	line-height: 18px;
+	margin-bottom: 5px;
+}
+
 .customize-control-color .color-picker,
 .customize-control-checkbox label,
 .customize-control-upload div {
@@ -333,6 +344,10 @@ body {
 	line-height: 22px;
 }
 
+.customize-control-radio .customize-control-title + .customize-control-description {
+	margin-top: 7px;
+}
+
 .customize-control-radio label {
 	line-height: 32px;
 }

wp-admin/css/customize-controls.css

@@ -275,6 +275,10 @@ body {
 	line-height: 24px;
 }
 
+p.customize-section-description {
+	font-style: normal;
+}
+
 .customize-control {
 	width: 100%;
 	float: left;
@@ -314,6 +318,13 @@ body {
 	margin-bottom: 5px;
 }
 
+.customize-control-description {
+	display: block;
+	font-style: italic;
+	line-height: 18px;
+	margin-bottom: 5px;
+}
+
 .customize-control-color .color-picker,
 .customize-control-checkbox label,
 .customize-control-upload div {
@@ -333,6 +344,10 @@ body {
 	line-height: 22px;
 }
 
+.customize-control-radio .customize-control-title + .customize-control-description {
+	margin-top: 7px;
+}
+
 .customize-control-radio label {
 	line-height: 32px;
 }

wp-includes/class-wp-customize-control.php

@@ -53,6 +53,12 @@ class WP_Customize_Control {
 	 */
 	public $label = '';
 
+	/**
+	 * @access public
+	 * @var string
+	 */
+	public $description = '';
+
 	/**
 	 * @todo: Remove choices
 	 *
@@ -258,7 +264,12 @@ class WP_Customize_Control {
 			case 'text':
 				?>
 				<label>
-					<span class="customize-control-title"><?php echo esc_html( $this->label ); ?></span>
+					<?php if ( ! empty( $this->label ) ) : ?>
+						<span class="customize-control-title"><?php echo esc_html( $this->label ); ?></span>
+					<?php endif;
+					if ( ! empty( $this->description ) ) : ?>
+						<span class="description customize-control-description"><?php echo esc_html( $this->description ); ?></span>
+					<?php endif; ?>
 					<input type="text" value="<?php echo esc_attr( $this->value() ); ?>" <?php $this->link(); ?> />
 				</label>
 				<?php
@@ -268,6 +279,9 @@ class WP_Customize_Control {
 				<label>
 					<input type="checkbox" value="<?php echo esc_attr( $this->value() ); ?>" <?php $this->link(); checked( $this->value() ); ?> />
 					<?php echo esc_html( $this->label ); ?>
+					<?php if ( ! empty( $this->description ) ) : ?>
+						<span class="description customize-control-description"><?php echo esc_html( $this->description ); ?></span>
+					<?php endif; ?>
 				</label>
 				<?php
 				break;
@@ -277,9 +291,13 @@ class WP_Customize_Control {
 
 				$name = '_customize-radio-' . $this->id;
 
-				?>
+				if ( ! empty( $this->label ) ) : ?>
-				<span class="customize-control-title"><?php echo esc_html( $this->label ); ?></span>
+					<span class="customize-control-title"><?php echo esc_html( $this->label ); ?></span>
-				<?php
+				<?php endif;
+				if ( ! empty( $this->description ) ) : ?>
+					<span class="description customize-control-description"><?php echo esc_html( $this->description ); ?></span>
+				<?php endif;
+
 				foreach ( $this->choices as $value => $label ) :
 					?>
 					<label>
@@ -295,7 +313,13 @@ class WP_Customize_Control {
 
 				?>
 				<label>
-					<span class="customize-control-title"><?php echo esc_html( $this->label ); ?></span>
+					<?php if ( ! empty( $this->label ) ) : ?>
+						<span class="customize-control-title"><?php echo esc_html( $this->label ); ?></span>
+					<?php endif;
+					if ( ! empty( $this->description ) ) : ?>
+						<span class="description customize-control-description"><?php echo esc_html( $this->description ); ?></span>
+					<?php endif; ?>
+
 					<select <?php $this->link(); ?>>
 						<?php
 						foreach ( $this->choices as $value => $label )
@@ -401,7 +425,13 @@ class WP_Customize_Color_Control extends WP_Customize_Control {
 		// The input's value gets set by JS. Don't fill it.
 		?>
 		<label>
-			<span class="customize-control-title"><?php echo esc_html( $this->label ); ?></span>
+			<?php if ( ! empty( $this->label ) ) : ?>
+				<span class="customize-control-title"><?php echo esc_html( $this->label ); ?></span>
+			<?php endif;
+			if ( ! empty( $this->description ) ) : ?>
+				<span class="description customize-control-description"><?php echo esc_html( $this->description ); ?></span>
+			<?php endif; ?>
+
 			<div class="customize-control-content">
 				<input class="color-picker-hex" type="text" maxlength="7" placeholder="<?php esc_attr_e( 'Hex Value' ); ?>"<?php echo $default_attr; ?> />
 			</div>
@@ -458,7 +488,12 @@ class WP_Customize_Upload_Control extends WP_Customize_Control {
 	public function render_content() {
 		?>
 		<label>
-			<span class="customize-control-title"><?php echo esc_html( $this->label ); ?></span>
+			<?php if ( ! empty( $this->label ) ) : ?>
+				<span class="customize-control-title"><?php echo esc_html( $this->label ); ?></span>
+			<?php endif;
+			if ( ! empty( $this->description ) ) : ?>
+				<span class="description customize-control-description"><?php echo esc_html( $this->description ); ?></span>
+			<?php endif; ?>
 			<div>
 				<a href="#" class="button-secondary upload"><?php _e( 'Upload' ); ?></a>
 				<a href="#" class="remove"><?php _e( 'Remove' ); ?></a>
@@ -540,7 +575,12 @@ class WP_Customize_Image_Control extends WP_Customize_Upload_Control {
 
 		?>
 		<div class="customize-image-picker">
-			<span class="customize-control-title"><?php echo esc_html( $this->label ); ?></span>
+			<?php if ( ! empty( $this->label ) ) : ?>
+				<span class="customize-control-title"><?php echo esc_html( $this->label ); ?></span>
+			<?php endif;
+			if ( ! empty( $this->description ) ) : ?>
+				<span class="description customize-control-description"><?php echo esc_html( $this->description ); ?></span>
+			<?php endif; ?>
 
 			<div class="customize-control-content">
 				<div class="dropdown preview-thumbnail" tabindex="0">

wp-includes/class-wp-customize-section.php

@@ -180,7 +180,7 @@ class WP_Customize_Section {
 			<h3 class="accordion-section-title" tabindex="0"><?php echo esc_html( $this->title ); ?></h3>
 			<ul class="accordion-section-content">
 				<?php if ( ! empty( $this->description ) ) : ?>
-				<li><p class="description"><?php echo $this->description; ?></p></li>
+				<li><p class="description customize-section-description"><?php echo $this->description; ?></p></li>
 				<?php endif; ?>
 				<?php
 				foreach ( $this->controls as $control )