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

[celloexpressions]

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.

[karmatosed]

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?

[celloexpressions]

@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]

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

[celloexpressions]

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.

[celloexpressions]

Action hook in themes panel header.

[celloexpressions]

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.

[karmatosed]

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.

[FolioVision]

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.

[westonruter]

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

[celloexpressions]

@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.

[celloexpressions]

This issue needs direction from the Theme Review Team. The core customize API provides numerous structured mechanisms for UI customization. The hook in 37335.diff​ should not be a preferred approach from a core perspective unless there is a strong need for it from a theme-review perspective. That appears unlikely based on the passage of time, but feel free to reopen.