Image Widget Merge Proposal


As part of this year’s Customization Focus, @westonruter, @obenland, @adamsilverstein, @timmydcrawford, @gonom9, and I have been working on creating an image widget for core. This new widget lets you quickly and easily add an image to your site’s widget areas.

You may have previously seen this come up as a media widget on Trac, before we decided to split the widget up into individual media-focused widgets. Having single widgets makes them more discoverable, and eases the way forward for similar blocks in the Editor. The image widget is the first in a series of media-focused widgets we’ll be introducing to core.

You can check out the widget on GitHub, install the plugin from WordPress.org, or check out the Trac ticket.

Why make an image widget?

People want to add images to their widget areas. Visit any subject blog across the internet and you’ll likely find images in the sidebars. People add photos of themselves along with bio blurbs, link to their books, promote upcoming events with graphics, partner with other blogs and exchange ads, and add call-to-actions using images.

The current process for adding an image to your widget areas is quite painful. You need to:

  1. Upload or select an image in your media library.
  2. Copy the image URL.
  3. Go to the widgets admin screen, or the widgets panel in the Customizer.
  4. Create a new Text widget.
  5. Add the image to the Text widget using HTML, which is often a barrier for new or non-technical site maintainers. (See #35243 for work to add a visual mode to Text widget.)

This is a huge barrier to what should be a relatively simple task. This new image widget makes it much easier to add an image to your widget areas by natively integrating with core’s media library.

How is it implemented?

There hasn’t been any new widget types added to core in a long time; the Custom Menu widget was the last widget added in WordPress 3.0—almost 7 years ago! (The core themes Twenty Eleven and Twenty Fourteen did include their Ephemera widgets since then.) Since widgets are a very old part of WordPress, widgets in core have been very much entirely built using PHP with some Ajax sprinkled on top. In the time since WP_Widget was introduced in 2.8, WordPress has made dramatic shifts toward developing interfaces in JavaScript, including with the Customizer in 3.4 and the Media Library in 3.5, and more recently with the focus on the REST API.

Given that the media widgets are naturally interfacing with the media library JS, it is necessary that the media widgets make use of JavaScript to construct their UI instead of relying on PHP. Initial groundwork for shimming JavaScript into widgets was added in 3.9 via the widget-added and widget-updated events. A more recent proposal for making JavaScript more of a first class citizen can be found in #33507 and the media widgets incorporate some of its patterns that were also prototyped in the JS Widgets plugin. The media widgets make use of a Backbone View to manage the widget control’s UI and a Backbone Model for reading and manipulating the widget instance data.

Another unique aspect of how the media widgets work is how instance data is sanitized. Normally widgets write procedural code to sanitize instances via a subclassed WP_Widget::update() method. The media widgets, however, make use of a REST API schema returned from WP_Widget_Media::get_instance_schema() to sanitize instances declaratively. The WP_Widget_Media::update() method iterates over the schema and uses it to sanitize and validate the instance properties. Adding schemas to the base WP_Widget class is also proposed in #35574.

Please test

Please test the image widget. For now, you can grab the latest version of the widget on GitHub. You can either check it out locally using Git, or download a zip by clicking “Clone or download” → “Download ZIP.” Alternately, you can download the nightly version of the plugin from the WordPress.org plugin directory.

#image-widget, #media-widgets