Changes to Customizer Sliding Panels/Sections in WordPress 4.7

Several updates to the customizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings.’s sliding panels/sections implementation are going to be introduced in WordPress 4.7. The changes are now available in trunktrunk A directory in Subversion containing the latest development code in preparation for the next major release cycle. If you are running "trunk", then you are on the latest revision., 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.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/ pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party 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 accessibilityAccessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/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 ticketticket Created for both bug reports and feature development on the bug tracker.: #34391.

The patchpatch A special text file that describes changes to code, by identifying the files and lines which are added, removed, and altered. It may also be referred to as a diff. A patch can be applied to a codebase for testing. 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 CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.).
  • 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.
  • CSSCSS Cascading Style Sheets. 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 HTMLHTML HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers. 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 JSJS JavaScript, a web scripting language typically executed in the browser. Often used for advanced user interfaces and behaviors./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 bugbug A bug is an error or unexpected result. Performance improvements, code optimization, and are considered enhancements, not defects. After feature freeze, only bugs are dealt with, with regressions (adverse changes from the previous version) being the highest priority. related to the update, feel free to add a comment here or directly in the TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. ticket: #34391.

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