Allow Customizer elements (controls, sections, and panels) to be deep-linked

[westonruter]

There should be a way to deep-link to controls, sections, and panels in the Customizer. This would facilitate directing users to the customizer sections that deprecate theme options pages in the WordPress admin (#28032).

Raised by celloexpressions in #27406:

It would be cool if we automatically built in a deep-linking mechanism to access specific panels immediately by their id when entering the customizer (future enhancement).

Also by westonruter in #28032:

It would also be great if the links from the Header Image, Background Image, and Widgets admin pages would be able to auto-expand (or highlight) their corresponding sections in the Customizer when it loads.

Note that during the merge of Widget Customizer into core for 3.9, there was actually a mechanism to deep-link to the widget customizer sections, but it was removed in [27891]: for the plugin, it was used in an admin notice linking the user from the widgets admin page to the customizer (see #28032).

With customizer deep linking in place, something else to explore later would be a facility for themes to add inline contextual links within the customizer preview to then reveal the corresponding control in the customizer. For example, clicking on the blog title should auto-expand the “Site Title & Tagline” section and add focus on the Site Title field. Likewise, clicking on the header image in the preview should expand the “Header Image” customizer section.

See also:

• #28032 Make Customizer more visible with visual cues on deprecated areas of the admin
• #25571 Remove Custom Header Page in favor of the Customizer
• #25569 Remove the Custom Background Screen in Favor of the Customizer
• #28536 Add browser history and deep linking for navigation in Customizer preview

[helen]

Punting, can be brought back if there's a patch in the next couple days.

[celloexpressions]

We should make #28536, #28709, and #28570 dependencies so that the implementation of this doesn't have to change once those happen. Would be nice to do this in 4.1, but those should happen first.

Think http://example.com/customize/widgets for deep-linking :)

[westonruter]

This is really a dependency for #25569 and #25571.

[westonruter]

celloexpressions also correctly notes that this depends on #28709, in that we need JS models for the panels and sections, especially, to cleanly expand/collapse/focus on the elements.

[wonderboymusic]

I am moving this into the backlog until there is a patch - there are a lot of Customizer tickets. If a patch materializes, great.

[celloexpressions]

This will be fairly trivial once #28709 happens, and could even happen as part of that (and can happen via alternate means if it doesn't), and is likely to be required for the header/background stuff that we want to get done here for 4.1 to go with Twenty Fifteen.

[celloexpressions]

We'll implement this using a URL query arg, ie

/wp-admin/customize.php?control=background-image&url=http%3A%2F%2Fdevelop.wp.dev%2F

There will need to be some code that grabs that, then finds the corresponding object (control, section, or panel) and invokes its focus() method, which is being implemented in #28709. Only one object would need to be provided, so we don't need to know what section a control is in, for example, that'll be handled internally.

[westonruter]

​https://github.com/xwpco/wordpress-develop/pull/40

[westonruter]

In 28650.partial.diff​, a patch that builds upon with in #28709:

• Export to JS the Customizer construct being deep-linked
• Short-circuit embed() if panel/section/control already embedded
• Add deferred.ready to Panel, Section, Control; embed when initialized
• Focus on a panel/section/control when ready
• Wait to autofocus on panel/section/control until element is embedded and preview has loaded. Use an animation of 0 until the preview loads.
• When focusing on panel/section/control, scroll into view
• Use ?autofocus[section]=colors pattern for query param

Now you can direct link to the widgets panel from the widgets admin page via: /wp-admin/customize.php?autofocus[panel]=widgets

@celloexpressions: Caveat being that the panel positioning is currently a bit finicky, especially regarding the margin-top and scroll position. But that's really an issue in #28709.

[ocean90]

In 30102:

Improve/introduce Customizer JavaScript models for Controls, Sections, and Panels.

• Introduce models for panels and sections.
• Introduce API to expand and focus a control, section or panel.
• Allow deep-linking to panels, sections, and controls inside of the Customizer.
• Clean up accordion.js, removing all Customizer-specific logic.
• Add initial unit tests for wp.customize.Class in customize-base.js.

​https://make.wordpress.org/core/2014/10/27/toward-a-complete-javascript-api-for-the-customizer/ provides an overview of how to use the JavaScript API.

props westonruter, celloexpressions, ryankienstra.
see #28032, #28579, #28580, #28650, #28709, #29758.
fixes #29529.

[westonruter]

celloexpressions: What do you think we should do about panel animations?

[westonruter]

Panel deep-linking still isn't working quite right. The panel's contents can fail to get positioned at the top: ​https://cloudup.com/cKlH-e25yOM

[ocean90]

The panel position issue will be handled in #28709.

[AlexandruDoda]

It seems that direct page linking + deep linking do not currently work together. For example:

​http://example.com/wp-admin/customize.php?autofocus[section]=section_login&url=http://example.com/wp-login.php

or

​http://example.com/wp-admin/customize.php?url=http://example.com/wp-login.php&autofocus[section]=section_login

Neither of these examples will open the page parsed through the url parameter and open the panel together. That would be pretty useful when linking to specific customization areas. In the example I wrote above, I am trying to create a button that links to a specific Customizer section after it opens that page since they are contextual / related.

[westonruter]

Replying to AlexandruDoda:

It seems that direct page linking + deep linking do not currently work together. For example:

​http://example.com/wp-admin/customize.php?autofocus[section]=section_login&url=http://example.com/wp-login.php

or

​http://example.com/wp-admin/customize.php?url=http://example.com/wp-login.php&autofocus[section]=section_login

Neither of these examples will open the page parsed through the url parameter and open the panel together. That would be pretty useful when linking to specific customization areas. In the example I wrote above, I am trying to create a button that links to a specific Customizer section after it opens that page since they are contextual / related.

The url you're providing is not valid, as you can't load the wp-login.php page into the Customizer preview. Supply a url param that contains a valid previewable URL, and you should see it load in the preview along with the supplied autofocus panel/section/control being focused.

[AlexandruDoda]

Replying to westonruter:

Replying to AlexandruDoda:

It seems that direct page linking + deep linking do not currently work together. For example:

​http://example.com/wp-admin/customize.php?autofocus[section]=section_login&url=http://example.com/wp-login.php

or

​http://example.com/wp-admin/customize.php?url=http://example.com/wp-login.php&autofocus[section]=section_login

Neither of these examples will open the page parsed through the url parameter and open the panel together. That would be pretty useful when linking to specific customization areas. In the example I wrote above, I am trying to create a button that links to a specific Customizer section after it opens that page since they are contextual / related.

The url you're providing is not valid, as you can't load the wp-login.php page into the Customizer preview. Supply a url param that contains a valid previewable URL, and you should see it load in the preview along with the supplied autofocus panel/section/control being focused.

Using the wp-login.php page as an URL parameter does open that page and customizing fields do apply on-page. I am basically using the Customizer to change login page CSS like background, form colors, etc. and it works. Why isn't the url considered valid?

Update - Demo: ​https://www.dropbox.com/s/63a7zq6oe49xbli/Customizer_login.mov?dl=0

[westonruter]

Replying to AlexandruDoda:

Using the wp-login.php page as an URL parameter does open that page and customizing fields do apply on-page. I am basically using the Customizer to change login page CSS like background, form colors, etc. and it works. Why isn't the url considered valid?

Update - Demo: ​https://www.dropbox.com/s/63a7zq6oe49xbli/Customizer_login.mov?dl=0

I was thinking of this bit of code in customize-controls.js:

this.add( 'previewUrl', params.previewUrl ).setter( function( to ) {
        var result;

        // Check for URLs that include "/wp-admin/" or end in "/wp-admin".
        // Strip hashes and query strings before testing.
        if ( /\/wp-admin(\/|$)/.test( to.replace( /[#?].*$/, '' ) ) )
                return null;

But I see now it is specifically for wp-admin and not wp-login.

I can see that deep-linking to wp-login.php does work, kindof. You'll notice that the document.title never stops showing Customize: Loading…. So it never finishes activating, and this is why I believe you're not getting any autofocusing going on.

Please open a new ticket, as I don't think Customizing the login page is really something that was anticipated from the beginning of the Customizer.

[westonruter]

In 36796:

Customize: Ensure autofocus deep-linking applies for dynamically-created panels, sections, and controls.

Removes overly-zealous filtering of autofocus panels, sections, and controls which are unrecognized or for which the user doesn't have the capability to focus (in which case it would no-op anyway). Also defers autofocus logic until instances are created, even after initial ready event. This ensures that autofocus can apply for any panels, sections, or controls that get created via the loaded preview.

See #28650.
Fixes #36018.