WordPress.org

Make WordPress Core

Opened 4 years ago

Closed 3 years ago

#27981 closed enhancement (fixed)

Support descriptions for Customizer Controls

Reported by: danielbachhuber Owned by: helen
Milestone: 4.0 Priority: normal
Severity: normal Version:
Component: Customize Keywords: has-patch commit
Focuses: Cc:

Description

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.

Attachments (4)

27981.diff (5.9 KB) - added by celloexpressions 3 years ago.
Implement descriptions for most core customizer controls, only output the control title & description markup if there's a title/description.
27981.png (22.2 KB) - added by celloexpressions 3 years ago.
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.
27981.2.diff (6.1 KB) - added by celloexpressions 3 years ago.
Fix margin on radio type title/descriptions.
27981.3.diff (4.2 KB) - added by tollmanz 3 years ago.
Patch removes esc_html around Customizer descriptions

Download all attachments as: .zip

Change History (18)

#1 @philiparthurmoore
3 years ago

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.

#2 @sdavis2702
3 years ago

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

@celloexpressions
3 years ago

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

@celloexpressions
3 years ago

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.

#3 @celloexpressions
3 years ago

  • Keywords has-patch added; needs-patch removed

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

#4 @SergeyBiryukov
3 years ago

  • Milestone changed from Future Release to 4.0

This ticket was mentioned in IRC in #wordpress-dev by celloexpressions. View the logs.


3 years ago

@celloexpressions
3 years ago

Fix margin on radio type title/descriptions.

#6 @celloexpressions
3 years ago

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

This ticket was mentioned in IRC in #wordpress-dev by helen. View the logs.


3 years ago

#8 @helen
3 years ago

  • Owner set to helen
  • Resolution set to fixed
  • Status changed from new to closed

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.

#9 follow-ups: @tollmanz
3 years ago

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.

#10 in reply to: ↑ 9 @westonruter
3 years ago

  • Resolution fixed deleted
  • Status changed from closed to reopened

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.

#11 in reply to: ↑ 9 @philiparthurmoore
3 years ago

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
3 years ago

Patch removes esc_html around Customizer descriptions

#12 @celloexpressions
3 years ago

  • Keywords commit added

Looks good.

#14 @helen
3 years ago

  • Resolution set to fixed
  • Status changed from reopened to closed

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.

Note: See TracTickets for help on using tickets.