WordPress.org

Make WordPress Core

Opened 13 months ago

Last modified 10 months ago

#37335 new enhancement

Standardized API for themes to add info/links to the customizer

Reported by: celloexpressions Owned by:
Milestone: Awaiting Review Priority: normal
Severity: normal Version:
Component: Customize Keywords: has-patch
Focuses: ui Cc:

Description

Currently, the theme review team allows themes to inject custom UI with an upsell link into the customizer, as a compromise provided that there is only one link. This creates several problems, such as providing an inconsistent experience for users when switching to different themes and potential breakage if core markup or UI changes. Since the customizer is API-oriented, there isn't generally a restriction to changing the markup or UI in core because custom things added via the API can still be backwards compatible.

If we can come up with a core UI that theme developers can opt into and probably supply a few parameters to, the experience can be standardized for users, developers can keep their links, and we can better encourage proper customization of the customizer via the API.

Technical implementation will be fairly straightforward - a matter of deciding if it should be something along the lines of add_theme_support or a custom section/control type in core that can be added directly. The bigger question is what this UI should look like, what information needs to be able to be provided, and whether it should be on the top level of the customizer or within a section or other nested UI.

See slack discussion: https://wordpress.slack.com/archives/themereview/p1468283558004173.

Attachments (3)

theme-pro-link-in-header.PNG (11.5 KB) - added by celloexpressions 11 months ago.
This is doing_it_wrong in terms of both UI/UX and code, but currently allowed by TRT.
theme-pro-link-in-header-example.PNG (15.2 KB) - added by celloexpressions 11 months ago.
An action hook in the themes panel heading could allow themes to add content more safely, while providing a standardized approach for adding links that could be more easily moderated by the TRT.
37335.diff (1.2 KB) - added by celloexpressions 11 months ago.
Action hook in themes panel header.

Download all attachments as: .zip

Change History (18)

This ticket was mentioned in Slack in #themereview by celloexpressions. View the logs.


13 months ago

#2 @karmatosed
12 months ago

I'm trying to work out what this needs UI wise, so please help me through this. Are you saying there would be a place where this upsell/link appears or a UI to add it?

This ticket was mentioned in Slack in #themereview by celloexpressions. View the logs.


11 months ago

#4 @celloexpressions
11 months ago

@karmatosed this is based on the TRT decision to allow themes to add upsell links to the top level of the customizer: https://make.wordpress.org/themes/2016/05/03/may-3rd-meeting-notes/. Unfortunately, most are doing_it_wrong both in terms of code (injecting markup with JS, which will break whenever core changes things) and usability (throwing links in places not relevant to themes, with bad text). The slack conversation linked above includes an example that I just noticed as well as a potential way that would be more acceptable in terms of working with core UI.

I'm now thinking that adding a do_action to the top-level themes section (soon to be panel) heading would be the best option all around. Then, the TRT can allow only links added via that action, which would ensure that the placement is appropriate and won't break if core markup changes. I'm hesitant to do more than that, such as forcing the UI to be a link, since it would be more complexity for core and overly restrictive for themes. However, I think the TRT should probably adopt some guidelines for what's added with this hook in term of UI, such as not allowing links to be styled as buttons.

I'll attach the images I shared in #themereview of a theme that's doing it wrong, and how it should probably be doing it instead.

@celloexpressions
11 months ago

This is doing_it_wrong in terms of both UI/UX and code, but currently allowed by TRT.

@celloexpressions
11 months ago

An action hook in the themes panel heading could allow themes to add content more safely, while providing a standardized approach for adding links that could be more easily moderated by the TRT.

This ticket was mentioned in Slack in #themereview by celloexpressions. View the logs.


11 months ago

@celloexpressions
11 months ago

Action hook in themes panel header.

#6 @celloexpressions
11 months ago

  • Keywords has-patch added; needs-patch removed

37335.diff is my proposal here, which would need to correspond with the Theme Review Team agreeing to allow top-level links only if they're added via this hook or a custom section. A theme would do something along the lines of:

add_action( 'customize_themes_panel_header', function( $panel ) {
	echo '<span class="customize-action"><a href="http://wordpress.org/">' . __( 'Theme documentation', 'theme-slug' ) . '</a></span>';
});

Note that the hook would move to a themes panel heading that is identical in #37661.

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


11 months ago

This ticket was mentioned in Slack in #themereview by jcastaneda. View the logs.


11 months ago

#9 @karmatosed
11 months ago

  • Keywords ui-feedback ux-feedback removed

I feel just having an action makes more sense than a fuller solution. Thanks for explaining. Because it's not UI related as a result, I will remove those tags in triage.

#10 @FolioVision
11 months ago

Nick, this is really important work you are doing here. Both providing the opportunity for promotion and limiting it. There should be strict guidelines

Right now the plugin admin interface and admin interface in general is an absolute mess due to too many "creative" approaches to self-promotion (admin notifications, stickies, unwanted dashboard elements, promotion in posts interface not to mention billboard style preference sections). All this needs to be trimmed back (another ticket, or rather several).

We have an opportunity here to stop this before it starts with the Customizer. I think we should provide guidelines and a template. It seems to me any theme which tries to get around the limits should be blocked in the customizer with a simple notice along these lines:

We notice that your theme breaks Customizer rules. To preserve a better user experience, we have blocked loading X Theme until it meets WordPress standards.

To protect the future of WordPress it's essential that we enforce some controls over the commercialisation of the admin space. Every time a theme or plugin creator pollutes the admin interface, s/he makes alternative platforms more attractive.

#11 @westonruter
11 months ago

@celloexpressions I wonder, however, if a new action is conflicting with our common mantra that JS should be used for extending the customizer UI?

#12 @celloexpressions
11 months ago

@FolioVision that's more on the theme review team side of things, but I imagine that there will eventually be a requirement to use the approach that we come up with here or to put UI within a section.

@westonruter more than JS, I'd say that custom controls/sections/panels and generally the PHP and JS APIs should be used to extend the customizer UI. Right now most themes that add promotional links are bypassing the API entirely and injecting content into the DOM with arbitrary JS, into core-defined UI elements such as the global header (implying that they're taking their site "Pro" by buying a custom theme, and in a way implying that they're getting a "pro" version of WordPress). An action would be a stopgap solution to provide a simple route that complies with core-recommended UI practices, and is the only good way I can think of to facilitate adding UI to a core section heading that should not be overridden by a custom instance. The other way is creating a custom section (which could display only a top level link and not expand), but that would introduce more UI for end users and more complexity for devs than being able to add a link via this action.

If you ask me, theme shouldn't be allowed to alter the top-level UI in any way, especially not with external links, but the theme review team decided to allow this so we need to make sure that it's possible to do in a reasonably elegant way that won't break things.

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


11 months ago

This ticket was mentioned in Slack in #themereview by greenshady. View the logs.


11 months ago

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


10 months ago

Note: See TracTickets for help on using tickets.