Make WordPress Core

Opened 9 years ago

Last modified 3 years ago

#34747 assigned enhancement

Provide more flexibility for "You are customizing" text

Reported by: danielbachhuber's profile danielbachhuber Owned by: ryankienstra's profile ryankienstra
Milestone: Awaiting Review Priority: normal
Severity: normal Version:
Component: Customize Keywords: has-patch needs-refresh close
Focuses: Cc:


I'd like to be able to customize the "You are customizing" text based on context:

Because these strings are rendered directly in wp-admin/customize.php, I have very little control over the text.

Ideally, this HTML would be rendered by calling WP_Customize_Panel::content_template() for the primary panel in the customizer (and I could have different primary panels for each view). However, if this abstraction is hairy, a filter for the title and description would suffice. If no description was present, the ? wouldn't appear. If no title were present, the informational section wouldn't appear.

Attachments (5)

34747.diff (1.7 KB) - added by ryankienstra 8 years ago.
b30b28.diff (1.7 KB) - added by ryankienstra 8 years ago.
a842df4.diff (4.0 KB) - added by ryankienstra 8 years ago.
2007d00.diff (11.7 KB) - added by ryankienstra 8 years ago.
b2088ce.diff (9.3 KB) - added by ryankienstra 8 years ago.

Download all attachments as: .zip

Change History (20)

8 years ago

#1 @ryankienstra
8 years ago

Patch That Filters Customizer Description

This patch and an identical GitHub PR filter the Customizer description, as you requested. If there's no description, it doesn't echo the ? button, which displays it.

Question About Filtering Title

It's definitely possible to filter the title. But it looks like it could be complex. The title is currently bound to the "blogname" setting at customize-controls.js#L3660:

title.text( $.trim( setting() ) || api.l10n.untitledBlogName );

This title is updated each time the "blogname" setting is updated in the Customizer's "Site Title" control. It's possible to override this. But it might not be what everyone expects.

Using content_template() To Filter Description
Maybe not yet practical

There are some differences between WP_Customize_Panel::content_template() and the panel that's currently echoed in customize.php. For example, content_template() doesn't have the id customize-info that content_template() has. And the content_template() method has a button that the current implementation doesn't have. So for now, this patch doesn't use content_template().

#2 @ryankienstra
8 years ago

  • Keywords has-patch added; needs-patch removed

#3 @westonruter
8 years ago

@ryankienstra thanks for the patch. A couple notes:

  • Probably best to not use esc_html() so that markup can be output if desired. Other controls description data is output without escaping to allow for markup.
  • Instead of customizer_primary_panel_description I'd suggest customize_root_panel_description panel (the term root is used elsewhere in the code to refer to the top-level).

As for overriding the title, that's a good question. For now probably the easiest is just to use JS to replace the elements and use different class names. If doing that, then you could also use JS to override the panel description, though this isn't the most elegant.

8 years ago

#4 @ryankienstra
8 years ago

New Patch That Corrects Description Filter
I Still Need To Apply Your Feedback On The Title Filter

Hi @westonruter,
Thanks for reviewing the original patch.

This new patch applies your feedback for the Customizer description filter:

  • Removes the escaping of the filtered string $customizer_description
  • Changes the filter name from customizer_primary_panel_description to your suggested customize_root_panel_description

The identical pull request on GitHub is also updated with a new commit.

8 years ago

#5 @ryankienstra
8 years ago

Patch That Adds "Title" Filter

Hi @westonruter,
This latest patch and identical PR may not be what you suggested. Could you let me know if they aren't?

As for overriding the title, that's a good question. For now probably the easiest is just to use JS to replace the elements and use different class names. If doing that, then you could also use JS to override the panel description, though this isn't the most elegant.

My PR filters the Customizer title and description in wp-customize.php. And it echoes them there, just like before.

If the title filter alters the title, I set a class on the element to prevent the title from being replaced in customize-controls.js. This may not be what you had in mind with using "JS to replace the elements."

I looked at ways to send the filtered title and description to customize-controls.js. But the entire panel is currently echoed in customize.php. It looks like there would be 3 variables that a PHP file would have to send to a JS file like customize-controls.js:

$is_title_filtered // to disable Customizer settings from overriding any updates to Customizer title

Since these variables are already produced in a .php file, I thought it might be cleanest to also output them in wp-customize.php. Instead of sending them to a JavaScript file to be added.

Please let me know if you had something else in mind. Or if there's a cleaner way to do this.

Version 0, edited 8 years ago by ryankienstra (next)

#6 @westonruter
8 years ago

@ryankienstra nice work. Adding a class name to indicate whether filters have applied is an easy way to do it.

If you need to pass these variables to the client, you could let the title and description be new class properties on WP_Customize_Manager, similar to the $preview_url, $return_url, and $autofocus properties that were added (see [34269]). These could then be exported to JS via WP_Customize_Manager::customize_pane_settings().

If there were new get_root_panel_title() and get_root_panel_description() methods on WP_Customize_Manager, the filters for customize_root_panel_title and customize_root_panel_description could be applied. Adding new methods to the manager class would allow them to be unit tested.

#7 @westonruter
8 years ago

  • Owner set to ryankienstra
  • Status changed from new to assigned

8 years ago

#8 @ryankienstra
8 years ago

Updated Patch And PR

Hi @westonruter,
Thanks for looking at my previous patch. Here is an updated patch and pull request.

As you requested, this uses WP_Customize_Manager to set and get the Customizer title and description. It adds these values to an array, which is available in customize-controls.js as api.settings.

This file also hides the "help" button if there's no description. And it hides the entire .customize-panel-description section if there's no title.

There are new unit tests for all of the new WP_Customize_Manager methods.

#9 @westonruter
8 years ago

@ryankienstra thanks! Feedback provided on PR.

8 years ago

#10 @ryankienstra
8 years ago

Status Update
Planning To Connect With Weston When 4.6 Begins

Thanks for your review of this ticket's pull request. For the record, attached is an updated patch with the same diff as the pull request.

Based on your comment on that pull request, I'll plan to connect with you at the start of the 4.6 cycle.

#11 @celloexpressions
8 years ago

Broader question: should we make this easily changeable in plugins? I'm generally of the opinion that the core base experience shouldn't be modified, only extended with custom UI in sections and panels, in most cases. It seems like hiding this section with CSS and adding a custom one, even if just for heading info may be the more appropriate approach, as that feels appropriately hacky for something that should only be done when absolutely necessary.

#12 @westonruter
8 years ago

The text is proposed to be removed entirely in #35186.

This ticket was mentioned in Slack in #core-customize by westonruter. View the logs.

8 years ago

This ticket was mentioned in Slack in #core-customize by celloexpressions. View the logs.

8 years ago

#15 @celloexpressions
3 years ago

  • Keywords needs-refresh close added
  • Milestone set to Awaiting Review

It would still be useful to allow filtering the root-level customize text. However, the majority of use cases should be using panel, section, and control descriptions instead of changing the root level. The valid use cases may be few enough that it's acceptable to omit the filter and let them change the DOM with JS.

I would propose holding on this pending resolution of #35186, and likely implementing this hook with the changes there if this text ends up staying.

Note: See TracTickets for help on using tickets.