Media meeting recap – June 29, 2017


This post is a summary of the latest weekly Media component meeting, which took place in #core-media on Slack, on Thursday, June 29 at 18:00 UTC. The purpose of these meetings are to move priority tasks forward, provide feedback on issues of interest, and review media focused tickets on Trac.

@joemcgill, @sergeybiryukov, @mikeschroder, @adamsilverstein, @desrosj, @azaozz, @karmatosed, @matias, @youknowriad, @mkaz, @joen.


Media + Gutenberg

Our agenda this week focussed on getting a better understanding of the current product vision for working with media in Gutenberg in order to coordinate priorities and ensure future improvements to the media component align with the needs of the new editor experience.

The major takeaway from this conversation was that Gutenberg intends to handle the UI flows for editing media within post content inside the editor itself rather than relying on the modal for these actions. The image gallery block in Gutenberg is a good example of this change.

Editing gallery settings in the current media modal

The current screen in the media modal for editing gallery settings


Editing gallery settings in the Gutenberg sidebar

A preview of editing image gallery settings in the Gutenberg sidebar

By handling post-level setting in the editor, people can immediately preview changes in the editor. This change reduces the burden of the current media modal to act primarily as media library, and as a way to manage media information that applies site-wide. This should also make it more clear when changes will affect a media item site-wide, which is a nice UX win.

Some next steps

To prepare for this shift, we need to document the current flows that will need to be adjusted in order to support this separation between managing post-level data and site-wide media library data.

Additionally, the Gutenberg team asked for help creating blocks for additional media elements like video, audio, etc. The Gutenberg GitHub repo now contains a “media” label for collecting issues that relate to the media component.

Other housekeeping items

Earlier this week, @desrosj ran a separate bug scrub focussed on new tickets on the Media component. We plan on running separate scrubs throughout the 4.9 release cycle. If you’re interested in helping with that effort, please contact @desrosj or @joemcgill on Slack.

#gutenberg, #media, #media-library, #media-modal

New Customizer Media Controls in 4.3 and 4.2

Over the past several releases, the Customizer API has drastically improved its built-in media controls, empowering developers to leverage the power of the WordPress media management experience in themes and plugins with ease. WordPress 4.1 refactored the image and upload controls to leverage the media modal for the first time (see #21483). 4.2 abstracted this functionality to a new base media control class. And now in WordPress 4.3, we’ve added a control for cropped images. In this post, I’ll outline the recent changes in Customizer media controls and explain the differences between the available controls.


Before WordPress 4.2, all Customizer media controls saved the file url to their corresponding settings. While this facilitates quick access when using the value of the setting in themes and plugins, it makes it more difficult to access other information about that attachment, such as its title/caption, mime type, or in the case of images, accessing specific image sizes.

WP_Customize_Media_Control was introduced to allow this paradigm to change while maintaining backwards compatibility for the existing WP_Customize_Upload_Control and WP_Customize_Image_Control, which now extend the media control class (see #29215). The media control will save the attachment id for the selected media file to the Customizer setting, rather than the file URL. However, note that the default value of the setting must still be a URL, since a default attachment id doesn’t really make sense.

The media control can be used for any type of media, be it an image, audio, video, PDF document, or any other file format that your server supports. To restrict a media control instance to a particular type of content, use the mime_type parameter when adding the control:

$wp_customize->add_control( new WP_Customize_Media_Control( $wp_customize, 'audio_control', array(
	'label' => __( 'Media Control (audio)' ),
	'section' => 'media',
	'mime_type' => 'audio',
) ) );

When working with a setting corresponding with a media control, the sanitize_callback should generally be absint(), since a numerical id is expected. When using get_option() and get_theme_mod(), functions such as wp_get_attachment_url(), wp_get_attachment_image(), wp_get_attachment_image_src(), and even get_post() are useful depending on your needs, with each function taking the attachment id (value of the setting) as a parameter.

The full power of WP_Customize_Media_Control is realized when the control is extended to implement additional custom functionality in a custom child control. WP_Customize_Cropped_Image_Control is a great example of this in core. The core Customizer control classes provide several working examples of this; see wp-includes/class-wp-customize-control.php and wp-admin/js/customize-controls.js.


New in WordPress 4.3, WP_Customize_Cropped_Image_Control extracts functionality from the header image control to allow an image to be cropped to specific dimensions (see #29211). This offers a better user experience than automatic cropping in many cases when images of a certain size or aspect ratio are required in themes and plugins. In core, the new site icon feature relies heavily on the cropped-image control, implementing a child custom control to add additional site-icon-specific functionality.

The cropped image control comes with four custom parameters in addition to those available in the media control. These are used to specify the required (or recommended) image dimensions, as well as specifying whether alternative dimensions are allowed (the flex options). Here’s a typical usage when adding a cropped-image control:

$wp_customize->add_control( new WP_Customize_Cropped_Image_Control( $wp_customize, 'cropped_image', array(
	'section'     => 'background_image',
	'label'       => __( 'Croppable Image' ),
	'flex_width'  => true, // Allow any width, making the specified value recommended. False by default.
	'flex_height' => false, // Require the resulting image to be exactly as tall as the height attribute (default).
	'width'       => 1920,
	'height'      => 1080,
) ) );

The cropped-image control creates a child attachment of the original image attachment object for the cropped image, preserving the original version. The cropped-image attachment is given a context based on the control id (with _ replaced by -). The core control doesn’t currently use this, but it could be leveraged to query for previously-cropped images for a specific control to add a library feature in the future or in child controls. Be mindful that a version of the control id is stored in the database for cropped image attachments.

As with the media control, the cropped-image control saves the attachment id instead of the image URL. This can be useful for querying specific sizes of the image, but you’ll typically want the full size image at the cropped dimension. wp_get_attachment_image_src( absint( get_option( 'cropped_image_setting' ) ) ) should do the trick if that’s the case, when outputting the value of the setting.

#4-2, #4-3, #customize, #dev-notes, #media, #media-modal

Remember the Media Grid project It was original…

Remember the Media Grid project? It was original proposed back in the 3.7/3.8 cycle but never really took off — mainly due to our focus on The-Project-Formerly-Known-As-MP6 and the Widget team.

Since then, I’ve been working on a plugin in some spare time:

Its messy. Its basic. But I think there’s potential in the idea to bring the media modal’s layout to the Media Library. @helen created a GitHub repo for development: (Make sure you checkout the issues, especially:

I’m looking to form a team to work on this project. I think we could have something ready for 4.0, but 4.1 is a possibility as well. It all depends on you. 🙂

I’m looking for any-and-all help, but specifically 1-2 backbone-capable developers with familiarity with the Media Modal would be a huge help.

Maybe we can chat about this a bit during tomorrow’s Dev Chat. Outside of that, lets plan on meeting in #wordpress-ui this Friday, Apr 25 @ 16:00 UTC.

So, are you interested? Leave a comment below and/or join us on Friday. Thanks!

#media-library, #media-modal, #media-grid