Customizer: Widgets: If your theme only has one widget area, we should open it automatically

[melchoyce]

If your theme only has one widget area, we should open into that widget area without making you pass a widget area picking screen.

See Current Flow and Proposed Flow attached images for my proposal.

[westonruter]

Good idea. Probably the simplest way to implement this is to auto-expand a section upon expanding a panel if the panel only has one section in it. Likewise, when collapsing such a section, the panel could also be collapsed so that the user wouldn't ever land on a panel that has only one section in it.

Another possibility would be to eliminate the Widgets panel entirely in this case, and let the widget's sidebar be a root section. This may have some unintended consequences however and it would require some R&D.

[lukecavanagh]

@melchoyce 

Seems like a logical solution.

[celloexpressions]

+1

I like the idea of automatically expanding the section within a panel if there's only one section, since having to click through an extra layer of hierarchy is never good UX. We should make sure that the panel is collapsed when the section is collapsed as well. Both checks should be able to happen on the onChangeExpanded functions for panels and sections.

This would cause the panel description to be inaccessible, but I'm okay with that for a number of reasons. This change would also help discourage incorrect usage of panels containing only one section and would be handy when panels with active callbacks on the sections result in only one section being visible.

[karmatosed]

+1 to this.

[delawski]

Here's my patch proposal for the enhancement:

​https://github.com/xwp/wordpress-develop/pull/194

The panel is still technically expanded/collapsed even though there's only one section inside. This way everything looks the same from the programmatic point of view. However, CSS transition is temporarily disabled on the panel and the section is expanded automatically, so from the user point of view the panel is invisible all the time.

[westonruter]

There's one additional scenario that this needs to accommodate, and that is what happens when a widget area section is deactivated due to the previewed template not doing dynamic_sidebar(). In that case, the panel actually still needs to be accessible so that the message can be displayed about there not being any widget areas that are displayed in the preview. I think the patch on this ticket actually is handling it properly, however it is difficult to test because of another bug: #39430.

What I'd want to happen is when a theme only has one widget area registered and this widget area is displayed in the preview, clicking on the Widgets panel should result in auto-expanding the widget area section as well. If I then click to a URL that does not have the sidebar rendered, I then expect that section to collapse and for me to be dropped onto the Widgets panel. In the same way, if I am at the root of the customizer UI and I am previewing a template that lacks the rendered sidebar, clicking the Widgets panel should just expand the panel and show the notice. Once navigating to a URL in the preview that has a rendered sidebar, either the section can just be revealed in the panel allowing me to click it to expand it, or the section can then auto-expand.

In any case, to test this properly we need to wait for #39430 to land.

/cc @dlh

[westonruter]

One more thing: I think the behavior of auto-expanding a panel's only section should probably be opt-in. We know that we want it for widgets, but for themes and plugins that have their own custom panels, they may very well want to be able to show a panel with just one section as the custom panel UI may have additional controls at the panel level.

So there could be a new WP_Customize_Panel::$auto_expand_sole_section = false param added, which for widgets we'd set it to be true.

[westonruter]

Another thing I noticed: if I have an autofocus param added for a widget control or the sidebar section as a whole, for example:

http://example.org/wp-admin/customize.php?autofocus[control]=widget_media_image[3]
http://example.org/wp-admin/customize.php?autofocus[section]=sidebar-widgets-sidebar-1

When I load the customizer it only expands the panel. The sidebar section does not get expanded.

[celloexpressions]

Replying to westonruter:

One more thing: I think the behavior of auto-expanding a panel's only section should probably be opt-in. We know that we want it for widgets, but for themes and plugins that have their own custom panels, they may very well want to be able to show a panel with just one section as the custom panel UI may have additional controls at the panel level.

So there could be a new WP_Customize_Panel::$auto_expand_sole_section = false param added, which for widgets we'd set it to be true.

Given the purpose of panels beyond the way the UI currently works, single-section panels should probably always expand the section by default. Custom panel types can alter that behavior, but in cases where they're using core UI and adding things to a panel "level"'s view, that should be done via the API, with additional custom sections and controls. Menus are a good custom panel example here, and the additional panel-level UI is to add new menus. This is actually done with a custom section, so there's no need to prevent that from opening a single default-like section because there's another section in the panel used to add the additional UI. Another good example is #37661, where it actually auto-expands the first section by default because both the panel-level and section-level UI are displayed at the same time.

[westonruter]

@celloexpressions my concern is that this is a backwards-incompatible change. For example, in the Customize Posts plugin there is a panel for each post type. The panel has a custom header area which adds a Select2 dropdown for selecting a page to edit. If you have a page in the preview, there will be one section added automatically in that panel for the controls for manipulating that page's settings. If auto_expand_sole_section is enabled by default, then the panel could not be navigated to in this case. So I think it should be an opt-in param that we enable specifically for widgets. Themes and plugins can also opt-in for it, and for the sake of back-compat with existing expected behavior, I think it should be opt-in.

[westonruter]

The auto_expand_sole_section param for WP_Customize_Panel is added in ​https://github.com/xwp/wordpress-develop/pull/194/commits/726214d11b9143c0b0d948dd18c73cf75551a004

What isn't working yet is what I described in 13, where autofocus isn't yet working with this auto-expansion behavior. Best way to test this is to activate twentyfifteen and then go to /wp-admin/customize.php?autofocus[section]=sidebar-widgets-sidebar-1. You'll see the Widgets panel only expands. It might be due to all of the active states being synced from the panel yet, and we should wait to autofocus until they have all been set.

[swissspidy]

Punting for now. Feel free to re-add to milestone when this is really ready for 4.7.4. As it's not a regression in 4.7, 4.8 or perhaps 4.7.x really makes more sense.

[westonruter]

​https://github.com/xwp/wordpress-develop/pull/194/commits/e9d4349624a832e1b73d9bdbaa17b44f5255f4ee

[westonruter]

Replying to westonruter:

What isn't working yet is what I described in 13, where autofocus isn't yet working with this auto-expansion behavior. Best way to test this is to activate twentyfifteen and then go to /wp-admin/customize.php?autofocus[section]=sidebar-widgets-sidebar-1. You'll see the Widgets panel only expands. It might be due to all of the active states being synced from the panel yet, and we should wait to autofocus until they have all been set.

This is fixed in 37471.0.diff​. Just a ​trivial omission.

Ready for testing.

[westonruter]

@melchoyce one more consideration I think is needed here, and that regarding activated vs inactive sections. For example, with #39087, the active sections for widget areas change based on which page you are previewing. So should auto-expansion happen when there is one section in a panel period, or when there is one section active? What if there is only one section but it is not active? Depending on the condition, the notice added in #39087 would not be displayed to the user. I think the proper answer is that auto-expansion should be done when: (1) there is one section associated with the panel, and (2) this one section is active. Otherwise, auto-expansion should be disabled.

[melchoyce]

Replying to westonruter:

I think the proper answer is that auto-expansion should be done when: (1) there is one section associated with the panel, and (2) this one section is active. Otherwise, auto-expansion should be disabled.

This is a little more complicated, but I think it's likely the best approach. 👍

[westonruter]

​https://github.com/xwp/wordpress-develop/pull/194/commits/a1ae2a6e9cfe40d17f11d2d2ffc9aa492518be3f

[westonruter]

37471.1.diff​ implements the change to only auto-expand a solitary section when it is active. However, there is an issue I'm seeing when when opening the customizer with autofocus on the widgets panel when there is only one widget area section but it is not active: the contents of the panel are shifted over halfway out of view due apparently to some issue with animations and transforms. See widgets-panel-autofocus-issue.png​. Help appreciated.

[delawski]

@westonruter I've noticed some issues with when and where the completeCallback is fired.

In my latest patch the callback is called only one time, no matter if the animation is shown or skipped. Also, in case the animation is not skipped, the callback is fired after its completion. In most cases firing the callback before the animation has finished causes layout quirks like the one described above.

The patch: https://core.trac.wordpress.org/attachment/ticket/37471/37471.2.diff

[westonruter]

@delawski great, that fixed the issue I observed! Great job. Tested in IE9, IE11, Chrome, Safari, and Firefox.

@melchoyce one more thing I realized that I think needs to be addressed here. If the panel gets skipped from being shown when there is only one widget area, this means that the general help text added to the panel is not then shown. So this this help text from the panel:

Is not also shown in the section where instead the description of the sidebar is shown instead:

So how about this: what if we combine the description from the panel with the description from the sidebar and put them into the same collapsed description in the section like appears on the panel, in other words:

This is implemented in ​https://github.com/xwp/wordpress-develop/pull/194/commits/d23b3d51cf85991dbf5743e035479f6a6d67b223

[westonruter]

​https://github.com/xwp/wordpress-develop/pull/194/commits/d23b3d51cf85991dbf5743e035479f6a6d67b223

[melchoyce]

Talked to some folks and the consensus seems to be that text isn't particularly helpful, so it's okay to not show it here.

Aside, I'd like to look at improving the help text across the Customizer (like we started doing in #40104) and consider showing the help text by default on new installs. I'll make a separate ticket for that later.

[westonruter]

OK, I'll commit then without that ​last change.

[westonruter]

In 40395:

Customize: Auto-expand a widget area section when expanding the Widgets panel if there is only one registered sidebar and it is active.

Introduces WP_Customize_Panel::$auto_expand_sole_section property which allows panels to opt-in to the behavior, which the Widgets panel is made to do by default.

Props delawski, westonruter, melchoyce.
Fixes #37471.

[westonruter]

Re-opening for consideration in 4.7.4

[swissspidy]

In 40402:

Customize: Auto-expand a widget area section when expanding the Widgets panel if there is only one registered sidebar and it is active.

Introduces WP_Customize_Panel::$auto_expand_sole_section property which allows panels to opt-in to the behavior, which the Widgets panel is made to do by default.

Props delawski, westonruter, melchoyce.
Fixes #37471.

Merges [40395] to the 4.7 branch.