readme.md

Widget Customizer

Edit widgets and preview changes in Theme Customizer, with a control for each widget form in sections added for each sidebar rendered in the preview.

Contributors: xwp, westonruter, shaunandrews, michael-arestad, johnregan3, akeda, topher1kenobe, topquarky, bobbravo2, ricardocorreia
Tags: customizer, widgets, sidebars, preview
Requires at least: 3.7
Tested up to: 3.8.1
Stable tag: trunk (master)
License: GPLv2 or later

Description

This plugin is being developed as part of the Widgets UI Refresh feature-as-plugin group. Read the Widget Customizer Feature-as-Plugin Merge Proposal.

New: This plugin has been merged into WordPress Core! See r27419. This plugin will deactivate itself when WordPress is updated to this revision.

Notice regarding empty sidebars: Unless you are running trunk, you won't be able to add widgets to empty sidebars. This is because the temporary hooks necessary are removed in final releases. So you must currently add at least one widget to each sidebar (in the traditional way) for it to appear in the customizer.

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 this plugin makes possible.

Each registered sidebar on your site gets its own section in the Customizer panel. Within each Sidebar Widgets section, each widget added to the sidebar will appear in order and its widget form will appear there just as it appears when editing widgets in the WordPress widgets admin page. Upon making a change to the widget form, press the form's Apply button to then see the changes in the preview window and to stage the widget changes for committing once the Save & Publish button is clicked. Again, changes made when in the Customizer do not appear until you hit this 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.

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.

Customizer control sections for sidebars will be shown or hidden dynamically when the the preview window is initially loaded or when navigating the site within the preview window, based on whether or not the sidebar got rendered in the previewed page. Only sidebars which can be previewed will be shown in the customizer panel.

While all themes and widgets can work with Widget Customizer, for the best experience the themes and widgets need to indicate they support live previews of 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. See Read more about §Live Previews.

No longer do you have to edit your widgets blind!

And here's an awesome bonus: since the widgets are registered as settings in the customizer, if you also have the Settings Revisions plugin also activated, the widgets will then get versioned! Each time you save your changes, the current instance of each widget will be saved in a revision, and you can restore a previous widget state by rolling back the settings revision.

Development of this plugin is done on GitHub. Pull requests welcome. Please see issues reported there before going to the plugin forum.

Live Previews

While all themes and widgets can work with Widget Customizer, by default each change to a sidebar or widget will result in the preview window being refreshed (settings default to transport=refresh), resulting in a delay before the changes can be seen. As of v0.10, changes to sidebars and widgets no longer require a full page refresh of the preview window in order to see the changes applied. To enable a much more responsive preview experience, themes and widgets must indicate that they support Widget Customizer live previews (which will, in part, add transport=postMessage for the relevant settings).

All core widgets and themes distributed with WordPress core are supported by default. For other themes, simply add 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 a 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 add_filter( 'customizer_widget_live_previewable_{id_base}', '__return_true' );. As with sidebars, if a widget has dynamic behaviors which normally only get added when the page first loads (e.g. 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 respectively, 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.

Screenshots

Before any changes have been made; widgets appear in sections corresponding to their assigned sidebars

After a change is made, the widget's Apply button is pressed to then see changes in preview and so changes can be published

Widgets can be added in sidebar sections; widgets get added to the top, and can be dragged into the desired location

Widgets can be trashed while in customizer, causing them to be moved to the Inactive Widgets sidebar

Widgets are be rearranged by drag-and-drop, and widgets can be assigned to other sidebars by dragging them over

Browse available widgets to add via a panel that slides out

I DON'T ALWAYS TEST MY WORDPRESS WIDGETS IN PRODUCTION, BUT WHEN I DO I USE THE WIDGET CUSTOMIZER PLUGIN

Changelog

0.15.1

• As of r27419 in WordPress Core trunk, the functionality in this plugin has been merged into core! This plugin will deactivate itself when WordPress is updated to this revision.

0.15

• Add support for wide widget controls by sliding them out horizontally over the preview. Fixes #18. PR #89. Props westonruter.
• Eliminate Update button and so preview updates with each input change for widgets that support live previews. Fixes #45. PR #93. Props westonruter.
• Make widget form controls more compact on smaller screen resolutions. PR #88. Props michael-arestad.
• Improve styling of widget search field. Fixes #83. Props shaunandrews.
• Rename "Update" button to "Apply". PR #80. Props arnoesterhuizen.
• Prevent error when initializing sidebar containing unregistered widget. Fixes #91. Props westonruter.
• Only show one widget form control expanded at a time. Props westonruter.
• Eliminate use of filter_input(). PR #74. Props westonruter.
• Add live preview support for Twenty Fourteen Ephemera Widget.
• And other changes...

0.14

• Add keyboard-accessible means of reordering widgets. Fixes #21. Props michael-arestad.
• Allow movement of widgets to other sidebars to be live-previewed (not needing page refresh). Props westonruter.
• Add widget icon defaults. PR #75. Props michael-arestad.
• Bugfix for handling keypress in available widgets panel. PR #72. Props knishiura-lab.
• Add theme support for Twenty Fourteen. Props westonruter.
• And other changes...

0.13

• Widget addition panel now features the use of a vector font for the widget icons instead of using PNGs. Fixes #69. Props michael-arestad.
• Fade widgets not rendered in sidebars on currently-previewed URL (very helpful when using Jetpack's Widget Visibility or the like). Fixes #65. Props westonruter.
• Sanitize all settings, including widget instances and sidebar manifests. Serialize widget instances using PHP's serialize instead of using JSON, since there may be values which cannot be represented in JSON. Ensure that backslashes are not dropped from widget instances. Fixes #28. Props westonruter.
• Wrap available-widgets in widgets-left for compatibility with plugins which look for widget templates in that element. Fixes #51. Props westonruter.
• Fix rendering widgets adjacent to hidden widgets. Props westonruter.
• Improve handling of widget updates which yield no instance changes. Props westonruter.
• Add temp filter to JS-sanitize values for settings which are no longer extant or if they need to be sanitized in an environment where the customizer is not initialized; done specifically for the Settings Revisions plugin. Props westonruter.

0.12

• Delete widgets directly if they have not been previously-saved; if a widget has been previously saved, removal of the widget moves it to the inactive widgets sidebar. Fixes #46. Props westonruter.
• Facilitate widgets opting-in to indicate customizer support via a widget option passed via constructor; this is in addition to the filter method. Fixes #67. Props westonruter.
• Auto-open sidebar section in customizer when accessed via notice on widgets admin. Fixes #32. Props westonruter.
• Animate toggling of active/inactive sidebars. Fixes #9. Props westonruter.
• Hide sidebar sections initially to prevent FOIS (flash of inactive sidebars). Fixes #36. Props westonruter.
• Close available widgets panel when previewed URL changes. Props westonruter.
• Remove default live preview support from children of core twenty* themes. Props westonruter.
• Fix submission of selected widget with “enter” keypress on filter input. Props westonruter.
• Fix top widget padding and broken borders. Props westonruter.

0.11

Introduce new panel for browsing and selecting widgets to add to a sidebar. This replaces the select dropdown that appeared at the top of the sidebar's widget controls. Props shaunandrews, westonruter. Fixes #58.

0.10.1

• Require shift key when clicking on a widget in the preview to open and focus on the widget in the customizer. Props westonruter.
• Prevent edge case error where dynamic_sidebar is called for a non-registered sidebar. Props westonruter.

0.10

Allow themes and widgets to support previewing changes to sidebars and widgets without resorting to refreshing the entire preview window. Props westonruter. Fixes #37.

0.9.6

Skip over instances for widgets no longer registered (as core does), eliminating assertion warnings. Props westonruter. Fixes #48.

0.9.5

Fix padding for widget customizer controls in WordPress 3.8. Props westonruter. Fixes #57.

0.9.4

• Add demo video to readme. Props topher1kenobe.
• Apply some jshint fixes and update plugin dev library

0.9.3

• Fix HTML markup breaking customizer "Collapse" link position.
• Trigger widget update when hitting enter in control input. Fixes #47.

0.9.2

Fix addition of previously-uninstantiated widgets to previously-empty sidebars. It was not possible to add new widgets to a fresh install. Props westonruter.

0.9.1

Render widget control templates into DOM for plugins to manipulate. The Jetpack Widget Visibility module expects the widget templates to be rendered into the DOM as hidden elements so that it can inject the "Visibility" button in the proper place. So we have to move the templates from the model and into the DOM for compat. Other plugins probably do this as well. Props westonruter.

0.9

• Add support for adding new widgets in the customizer. Widgets can now be added, reordered, modified, and deleted all in the customizer preview, without impacting any visitor to the site until you hit Save & Publish. Props westonruter. Fixes #3.
• Widgets in the customizer are now all properly model-driven, meaning that changes to the settings will trigger changes to the controls. This ensures that the Settings Revisions can work as expected, even allowing you to restore previously trashed widgets and restore previous widget orderings and sidebar placements. Props westonruter.
• Improve compatibility with plugins that add and extend widgets; the Jetpack Widget Visibility module now works fully in the customizer. Props westonruter. Fixes #39.
• Change widget button from primary Save to secondary Apply button. Props westonruter. Fixes #40.
• Attempt to prevent widgets from forcing their controls to be wide. Props westonruter. See #18.
• Update styles for compatibility with MP6. Props westonruter. See #33.
• Add initial unit tests. Props akeda (gedex). Fixes #25.

0.8

• Remove (trash) widgets from sidebars in the customizer and preview their removal before publishing the change. Removed widgets are moved to the Inactive Widgets sidebar accessible on the widgets admin page. Props topquarky (TrevorMills), westonruter. Fixes #22.
• Add keyboard-accessible way to expand/collapse widget form controls. Props topquarky (TrevorMills). Fixes #26.
• Add move cursor when hovering over widget form controls. Props westonruter.
• Feature link to Customizer on the Widgets admin page. Props johnregan3. Fixes #29.

0.7

• Make detection of sidebars in previewed template more robust by integrating new temp hooks available in trunk. Fixes #15.
• Allow widget form controls to be dragged to other sidebar sections. Fixes #24.
• Eliminate duplicated code by re-using wp_widget_control()
• Add PHPCS, JSHint, and Travis CI integration

0.6

Add drag-and-drop reordering of customizer controls, where the new order is itself previewed and is persisted until the settings are saved. Fixes issue #1. Props bobbravo2, westonruter.

0.5

Hovering over widgets in preview highlights corresponding customizer sections and controls in panel. Clicking a widget in preview opens widget form in panel and focuses on first input. Interacting with widget form highlights widget in preview. Note that this issue resolves a major usability problem illustrated by the user test video. Fixes issue #5. Props ricardocorreia, westonruter.

0.4

Render widget form controls in a collapsed state (with a toggle) as on the widgets admin page; add in-widget-title (#7). Props johnregan3.

0.3

• Add banner image (#10). Props johnregan3.
• Eliminate warning with an array type check

0.2

Only show customizer sections for sidebars which can currently be seen in the preview; sections show/hide dynamically as the preview frame is navigated.

0.1

First Release