Changes to Customizer Sliding Panels/Sections in WordPress 4.7

Several updates to the customizer’s sliding panels/sections implementation are going to be introduced in WordPress 4.7. The changes are now available in trunk, so you can test them with existing themes and plugins. It is worth noting that all instances of custom sections and panels in the WordPress.org plugin and theme repositories were checked by @celloexpressions. No conflicts were found, but still testing is advised.

tl;dr – The Solution

The root “panel” of the customizer (the links to the panels and panel-less sections) is now logically independent in the DOM from the panels and sections it links to, and likewise the links to sections within a panel are disconnected in the DOM from the container elements for the sections they link to. By keeping these separate, no margin-top hacks are needed anymore: the panel/section to be shown simply needs to be positioned to the top of the customizer pane. This also means accessibility hacks which set the root of the customizer to visibility:hidden but a nested child element to visibility:visible are not needed anymore (see #33258). To maintain the accessibility benefit that came “for free“ with the previous nested hierarchical unordered list, aria-owns property has been implemented to relate the panel/section links with the panel/section containers they link to.

For more context, please refer to the original ticket: #34391.

The patch should also fix related issues: #34344, #35947.

Flat Panels/Sections Structure

So far panels and sections markup was nested inside one huge ul list inside the customizer pane.

<div id="customize-theme-controls">
  <ul>
    <li id="accordion-section-foo" class="accordion-section control-section...">
      <h3 class="accordion-section-title">...</h3>
      <ul class="accordion-section-content...">
        <li class="customize-section-description-container">...</li>
        <li class="customize-control customize-control-text">...</li>
        ...
      </ul>
    </li>
    <li id="accordion-panel-bar" class="accordion-section control-section control-panel...">
      <h3 class="accordion-section-title">...</h3>
      <ul class="accordion-sub-container control-panel-content">
        <li class="panel-meta accordion-section...">...</li>
        <li id="accordion-section-baz" class="accordion-section control-section control-subsection">...</li>
      </ul>
    </li>
  </ul>
</div>

With #34391 being merged each panel/section content element is detached from the root “panel” and appended to the parent container #customize-theme-controls right after the root list.

<div id="customize-theme-controls">
  <ul class="customize-pane-parent">
    <li id="accordion-section-foo" class="accordion-section control-section..." aria-owns="sub-accordion-section-foo">
      <h3 class="accordion-section-title">...</h3>
    </li>
    <li id="accordion-panel-bar" class="accordion-section control-section control-panel..." aria-owns="sub-accordion-panel-bar">
      <h3 class="accordion-section-title">...</h3>
    </li>
  </ul>
  <ul id="sub-accordion-section-foo" class="customize-pane-child accordion-section-content accordion-section control-section...">
    <li class="customize-section-description-container">...</li>
    <li class="customize-control customize-control-text">...</li>
    ...
  </ul>
  <ul id="sub-accordion-panel-bar" class="customize-pane-child accordion-sub-container control-panel-content accordion-section control-section control-panel...">
    <li class="panel-meta accordion-section...">...</li>
    <li id="accordion-section-baz" class="accordion-section control-section control-subsection" aria-owns="sub-accordion-section-baz">
      ...
    </li>
  </ul>
  <ul id="sub-accordion-section-baz" ...>
    ...
  </ul>
</div>

A few additional notes:

  • New getContent() method of the Container class has been introduced.
    • It is responsible for the actual detachment of the content element (usually ul).
    • It should be overridden in the custom sections and panels if it makes more sense to not detach the content element from the parent and keep it nested.
    • It should also be overridden if custom expanding logic is used (e.g. ‘New Menu’ section in the Core).
  • New Container class properties are now available:
    • headContainer is a jQuery object containing the parent element (usually the li). So far the same object was kept in the container property.
    • contentContainer is a jQuery object containing the child element (usually the ul).
    • container is now a jQuery object with two members: headContainer and contentContainer. This way the backwards-compatibility is improved, as any jQuery methods working on a set of elements like find() or on() should still work with the container as before.
  • CSS classes that were possessed by the parent element are copied to the child container, which also is a way to improve the backwards-compatibility.
  • In order to keep logical relationship between the parent and the child elements (which no longer can be determined naturally from the HTML structure), the parent element has new aria-owns property. It lists all children elements of the container.
  • _recalculateTopMargin() method was dropped completely, as it is no longer relevant.

I highly encourage developers who have done any JS/CSS-heavy work with the customizer’s panels/sections to review the changes introduced by #34391 and test them with themes and plugins.

Transitioning translateX() Instead of left

Along the update to the inner structure of the panels/sections, the user experience of sliding panels has been improved. Now instead of transitioning left position of the container, translateX() is used. It makes the animation smoother and more performant.

  • A busy class has been introduced. It is added to the panels/sections that are going through CSS transition at a given moment.
  • The busy class is added and removed in the Container‘s new method: _animateChangeExpanded( completeCallback ). The method takes care of detecting if transitions are supported by the browser, initiating the transition and listening for normalised transitionend event. It takes one parameter, completeCallback, which is called when the transition is complete.

I hope that working with customizer’s sections and panels will be easier and more reliable with the new structure. If you find any bug related to the update, feel free to add a comment here or directly in the Trac ticket: #34391.

#4-7, #customize, #dev-notes