Support descriptions for Customizer Controls

[danielbachhuber]

Similar to how the Settings API has the "description" class and Customizer's Section class already supports descriptions, it would be nice if Customizer Controls also supported descriptions. The UI could be super minimal — a tooltip or similar would suffice.

[philiparthurmoore]

Huge +1 to this. I've found myself needing to write custom controls just so that I'm able to add in extra instructions underneath inputs.

[sdavis2702]

Another +1 here. I'm extending classes on multiple control types specifically for adding descriptions. This would be lovely in core.

[celloexpressions]

Implement descriptions for most core customizer controls, only output the control title & description markup if there's a title/description.

[celloexpressions]

27981.diff with several sample controls. The section description is no longer italicized to provide visual hierarchy between the section description and the control descriptions.

[celloexpressions]

I do like that not having the description option by default forces less UI clutter (at the expense of longer section descriptions), but it's definitely time to have a solution for this in core.

The implementation with 27981.diff​ is pretty straightforward:

$wp_customize->add_control( $setting_id, array(
	'label'       => $label,
	'description' => $description,
	'section'     => $section_id,
	'type'        => $type,
) );

I added support for descriptions in all core types/controls except for the following:

• dropdown-pages
• WP_Customize_Header_Image_Control
• WP_Widget_Area_Customize_Control
• WP_Widget_Form_Customize_Control

[celloexpressions]

Fix margin on radio type title/descriptions.

[celloexpressions]

27981.2.diff​ fixes inconsistent margins on the radio input type between the label and the description.

[helen]

In 28927:

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.

[tollmanz]

Super excited for this commit!

I have one suggestion: I think esc_html is unnecessarily restrictive and should be removed. Since these descriptions should never be populated via user input (and if they are, that's on the dev to work out), the description should be pre-escaped. I find this to be particularly limiting in that you cannot even add links or bold text.

[westonruter]

Replying to tollmanz:

I have one suggestion: I think esc_html is unnecessarily restrictive and should be removed. Since these descriptions should never be populated via user input (and if they are, that's on the dev to work out), the description should be pre-escaped. I find this to be particularly limiting in that you cannot even add links or bold text.

Agreed. A section's description lacks esc_html and so a control's description should omit it as well.

[philiparthurmoore]

Replying to tollmanz:

Super excited for this commit!

I have one suggestion: I think esc_html is unnecessarily restrictive and should be removed. Since these descriptions should never be populated via user input (and if they are, that's on the dev to work out), the description should be pre-escaped. I find this to be particularly limiting in that you cannot even add links or bold text.

Great catch here.

[tollmanz]

Patch removes esc_html around Customizer descriptions

[celloexpressions]

Looks good.

[DrewAPicture]

+1 for 27981.3.diff​.

[helen]

In 28980:

Don't escape customizer control descriptions, just as section descriptions are not escaped. These are set programmatically, not via user input. props tollmanz. fixes #27981.