Widget Customizer Feature-as-Plugin Merge Proposal

Widgets in WordPress provide an easy way to add functionality to predefined areas of your theme templates. However, once you add a widget to a sidebar you have to leave the WordPress admin to go back to the frontend to actually see how the updated widget appears in the sidebar on your site’s public frontend. While you are making these changes and experimenting with a widget, it could be completely broken and everyone visiting your site will see this broken widget since there is no core way to preview changes made to widgets. But WordPress also provides an excellent way to preview changes to various settings on your site via the (Theme) Customizer. Changes made when using the Customizer are not visible to site visitors until you hit Save & Publish. So what if widgets could be edited in the Customizer? That’s what the Widget Customizer plugin makes possible. No longer do you have to edit your widgets blind!

A widget control open the customizer

Each registered sidebar on your site gets its own section in the Customizer panel. Within each section, widgets appear in their sidebar order. The widget controls appear there just as they appear when editing widgets in the widgets admin page. Upon making a change to the widget control, pressing the form’s Update button causes the changes to appear in the preview window; no changes to the widgets are saved permanently for others to see until you hit the Customizer’s Save & Publish button. This goes for whether you’re adding a new widget, editing existing widgets, reordering widgets, dragging widgets to other sidebars, or even removing widgets from the sidebars entirely: all of these actions are previewable.

Adding a widget to a sidebar slides open a panel for browsing the available widgets, complete with the usual names and descriptions, but also featuring widget icons to help quickly identify widgets. The list of available widgets can also be filtered down with a search input.

When you remove a widget from a sidebar, it is not deleted. Instead, it is moved from an active sidebar to the “Inactive Widgets” sidebar which can currently be seen on the widgets admin page. As such, removing a widget now is the same as trashing a widget.

Adding a widget

Customizer control sections for sidebars are shown and hidden dynamically when the preview window is initially loaded or when navigating the site within the preview window, based on whether or not the sidebar gets rendered in the previewed URL. (You may not know this, but you can navigate your site by clicking links in the preview window.) Only sidebars which can be previewed will be shown in the customizer panel. Likewise, widgets that are not rendered in the preview (for example, by means of Jetpack’s Widget Visibility module) will appear in the Customizer as semi-transparent.

Accessibility has also been a key concern for Widget Customizer. The current keyboard navigation on the widgets admin page feels cumbersome, having to open screen options to enable a separate accessibility mode. We wanted to make re-ordering with widgets as seamless as possible. So now when any sidebar section is open, you can invoke a reorder mode to reveal up/down arrows to reorder widgets, as well as a subpanel to open for moving the widget to another sidebar entirely. (This feature is nearing completion in pull request #21.)

Here’s an older walkthrough of the plugin:

Live Previews

(This did not make it into WordPress 3.9 — that also means themes do not need to indicate support for the widgets customizer. Read more about Live Widget Previews: Widget Management in the Customizer in WordPress 3.9.)

While all themes and widgets should work with Widget Customizer, for the best experience the themes and widgets need to indicate they support live previews of sidebars and widgets. Without such support added, each change to a sidebar or widget will result in the preview window being refreshed, resulting in a delay before the changes can be seen (settings default to transport=refresh). To enable a much more responsive preview experience, themes and widgets should indicate that they support Widget Customizer live previews; this will update the relevant settings to use transport=postMessage, the updated widgets will be loaded via Ajax, and the widgets will be re-ordered via DOM manipulation.

All core widgets and themes distributed with WordPress core are supported by default. For other themes, simply include add_theme_support('widget-customizer') in your theme’s functions.php to opt-in. If your theme does some dynamic layout for a sidebar (like Twenty Thirteen uses jQuery Masonry), you’ll also need to then enqueue some JavaScript to listen for changes to the sidebar and reflow them when that happens; see the bundled support for Twenty Thirteen to see an example of what is required.

Along with themes needing to indicate support for live-previewable sidebars, widgets must also indicate that they support being live-previewed with Widget Customizer. When updating a widget, an Ajax call is made to re-render the widget with the latest changes, and then the widget element is replaced in the sidebar inside the preview. If a widget is purely static HTML with no associated script behaviors or dynamic stylesheets (like all widgets in core), then they can right-away indicate support for live previews simply by including 'customizer_support' => true in the array passed to WP_Widget::__construct(). As with sidebars, if a widget has dynamic behaviors which normally only get added when the page first loads (such as a widget which includes a carousel), then a script needs to be enqueued in the Customizer preview which will re-initialize the widget when a widget is changed.

The sidebar-updated and widget-updated events get triggered on wp.customize when sidebars and widgets get updated, each being passed the sidebar ID and the widget ID respectively as the first argument in the callbacks. For a full example demonstrating how to add theme support for live-previewing dynamic sidebars and how to add support for JS-initialized widgets, see this annotated Gist.

Core Tickets

A few Core tickets have been opened with patches to generally improve widgets and the customizer, and also to improve Widget Customizer itself:

  • #26633: Customizer form submission prevention impairs accessibility of links in customizer controls
  • #26061: Customizer settings with non-scalar values incorrectly trigger as changed
  • #26569: URLs exported to JavaScript in Customizer settings get double-encoded
  • #25368: Add temp hooks for Widgets UI Refresh plugin-as-feature
  • #26661: Add before/after hooks to override output of wp_widget_control()
  • #25419: Add support to widgets for icons and screenshots

User Tests

A couple user tests have been done, both of which went pretty well. More user testing is being queued up. Here’s the first user test video, though note it reflects an early rendition of the plugin:

Remaining Issues

In addition to wrapping up the keyboard-accessible widget reordering (#21), there is the dilemma of how to handle wide widget form controls (#18); various solutions have been proposed for how to display a widget control which does not fit within the customizer panel.

The other open issues are enhancements or open questions which may or may not need actioning.

Contributors

While the plugin was first conceived by me (@westonruter) and I’ve been the lead developer, a ton of valuable input and contributions have come from @shaunandrews, @michael-arestad, from my X-Team colleagues (@johnregan3, @akeda, @topher1kenobe), and from others in the community (@bobbravo2, @topquarky, @ricardocorreia).

Development on the plugin has been done on GitHub, with the WordPress.org repo serving as a read-only mirror.

See Also