xwp / wp-core-media-widgets

Feature plugin for development of new core media widgets for image, video, and audio (and others)

Core Media Widgets

Feature plugin for introducing new core media widgets for images, audio, and video.

Contributors: wordpressdotorg
Tags: sidebar, widget, images, video, audio, tinymce
Requires at least: 4.8.0
Tested up to: 4.9.0-alpha
Stable tag: master
License: GPLv2 or later

Description

See Trac tickets:

• NEW #35243: Add gallery widget.
• #32417: Add new core media widget
• #39993: Introduce Core Widget: Image
• #39994: Introduce Core Widget: Video
• #39995: Introduce Core Widget: Audio
• #35243: Extending the text widget to also allow visual mode

Media widgets from this plugin are planned to be copied into core and deactivated in this plugin in future releases.

For contributing patches to this plugin and for following developments, please see its GitHub project.

Changelog

[0.2.0] - 2018-09-18

Introduce gallery widget. See #120. Fixes #62.

[0.1.0]

Work in progress.

wp-core-media-widgets's Issues

Replace button in Edit Image window duplicates functionality of Change Image action

The Replace button in the Edit Image/Image Details modal duplicates the functionality of the Change Image button.

I'd suggest removal of the button from Edit Image, unless there's a different UX reason for leaving it in.

Address flash of replaced content in widgets admin screen

On the widgets admin screen, saving a widget causes the new form's contents to be sent back from the server and they replace the previous form, followed by invoking widget-updated event. Since there are JS components in the media widget which need to be re-initialized, and the result here is the Media Element being destroyed and rebuilt each time you save the widget and there is a flash of replaced/uninitialized content, with prior to save.

This is a relatively small issue, but it is an annoyance. Widgets in the customizer don't do this same form replacement behavior if the widget's form callback returns the same inputs as already exist in the DOM.

A more modern way to integrate JS components into widgets is explored in the JS Widgets feature plugin. Nevertheless, the JS Widgets plugin is too large in scope for a minor release to get media widgets out for users sooner rather than later, but at least I'd hope that we can keep it in mind.

---

For reference, given a widget that looks like this:

For the moment immediately after saving it will look like this:

Add PHPUnit tests

PHP unit tests (via PHPUnit) need to ensure the instance props get sanitized as expected when calling WP_Widget_Media::update() and also that they get rendered as expected when calling WP_Widget_Media::widget().

---

Since these widgets heavily use JavaScript we should be including QUnit tests as well. Beyond PHPUnit and QUnit, I also want to take this as an opportunity to implement acceptance tests via Codecetion or Behat. For more, see #34693.

Add QUnit tests

Test image widget on supported browsers and devices

• Full support back to IE11, partial back to IE8.
• Firefox, Chrome, Safari: Current – 1.
• iOS Safari: Current – 1.
• Android browser: Current major.
• Chrome/Android: Current.

Add comments below with relevant screenshots and which browsers/devices have been tested. Once done, check of the boxes.

Image widget alt and title attributes

Just quickly tested the Image widget:

• seems the alt attribute is not set on the preview in the WIdgets screen or in the Customizer sidebar
• in the frontend instead, it is set. But there's also a title attribute that shouldn't be there.

Also, I'm not sure about which alt attribute is used. The one from the media library or the one from the "Image Details" media modal"? Which one should prevail? And should one of those actually overwrite the other one or maybe users want to keep one default alt attribute in the Media Library and have a different alt attribute in the frontend, depending on the actual use context of the image?

Implement video widget

The video widget was disabled with the refactor in #17, and the WP_Widget_Video class needs to be refactored to match what was done for the WP_Widget_Image class, including the creation of a Backbone View VideoWidgetControl and VideoWidgetModel according to what was done for the image widget.

See #31 for the same for audio.

Improve rendering of video poster images

Improve rendering of poster images when ME.js will show YouTube or Vimeo players with their own poster frames underneath.

Captioned images overflow sidebar

Because captions get a hardcoded pixel width, they almost always overflow the sidebar. Fixing this would require changing the core shortcode to accept inline styles

Implement audio widget

The audio widget was disabled with the refactor in #17, and the WP_Widget_Audio class needs to be refactored to match what was done for the WP_Widget_Image class, including the creation of a Backbone View AudioWidgetControl and AudioWidgetModel according to what was done for the image widget.

See #32 for the same for video.

Alt and caption text are not shown

Just a reminder that alt or caption text aren't hooked up yet.

1. Go to the Customizer and Click Edit media.
2. Add Alt or caption text.
3. Go back and you don’t see the alt or caption text.

Media meda shouldn't sync automatically when selecting media in the media widget

see https://core.trac.wordpress.org/ticket/40403

Update widget descripton

From:

Displays an image file.

To:

Displays an image.

Because we're not displaying the file, we're displaying the image :)

Explore migration path for Jetpack to re-use core Image widget

It would be beneficial to find out if Jetpack's Image widget could be updated to defer to the new core image widget if it is available.

Refactor MediaWidgetControl#renderPreview() to return rendered template

Currently the JS that a media subclass writes for the renderPreview method looks something like this:

var control = this, previewContainer, previewTemplate;
previewContainer = control.$el.find( '.media-widget-preview .rendered' );
previewTemplate = wp.template( 'wp-media-widget-video-preview' );
previewContainer.html( previewTemplate( { attachment: control.selectedAttachment.attributes } ) );

The logic that a subclassed method needs to implement could be simplified down to just:

var previewTemplate = wp.template( 'wp-media-widget-video-preview' );
return previewTemplate( { attachment: this.selectedAttachment.toJSON() } );

There can be another method in MediaWidgetControl which is responsible for calling renderPreview and then injects the markup returned to inject into the proper DOM element.

Remove floats

We included every attributed afforded to regular images, but floats don't really work in this context, and could potentially mess up people's layouts. Let's remove.

Refactor JS to use an extensible Backbone View

The current wp.MediaWidget is used primarily as a namespace for methods that are event handlers for the widget-added and widget-updated events. I think we can clean this up by creating a base Backbone View for representing a Media widget which can then be extended for the various media types being represented. Then, similarly to how the customizer has wp.customize.controlConstructor there can be a lookup of media type (widget id_base) to the specific View subclass that is responsible for managing the state of the media widget form.

When image is deleted, only show 'Select Image' link

When I use an image for the widget from my media library and later delete it, the widget interface correctly shows that the image is missing:

The buttons below the image are incorrect, it should only show 'Select Image' as in the default state of the image when no image is selected:

Test video widget on supported browsers and devices

• Full support back to IE11, partial back to IE8.
• Firefox, Chrome, Safari: Current – 1.
• iOS Safari: Current – 1.
• Android browser: Current major.
• Chrome/Android: Current.

Add comments below with relevant screenshots and which browsers/devices have been tested. Once done, check of the boxes.

Allow the widgets to be overridden or disabled or to be filtered

I have implemented my own version of an Image Widget and it has such capabilities that allow a user to set specific details for each image that override the media gallery. Also added is the ability to add a specific url link, proper rel, custom sizing, and custom classes. This comes in handy when targeting specific user actions.

It would be great that these core widgets could be disabled / overridden so they do not conflict or if the core widgets allow for custom filtering / adding custom fields such like this one.

URL set when clicking "Change Image"

When clicking "Change Image" for an existing image that is set via URL - the current image widget URL is set in the selection window. Performing the same flow when changing an image from the media library, the current image is not selected:

Change Image: Current Image set via URL

Change Image: Current Image from media library

Note in the media library selection, the attachment details are shown in this selection view too, and they probably should not.

While not a blocker, if one is trying to change images via URL you have to select all/remove the existing URL to enter a new one.

Image Widget: Edit screen doesn't pick up file and post links

When images are linked to their file or attachment page, the url to that page never gets passed to the image model, resulting in the edit screen always assuming it's not linked at all.

To reproduce:

1. Select an image
2. For "Link to", either select "Media File" or "Attachment Page".
3. Click "Add to Widget"
4. Click "Edit Image"
5. Check the "Link to" field.

mediaFrameProps never get linkUrl set when link is either "file" or "post".

Attachment details show before image is selected

You can see here that I don't have an image selected yet, but the attachment details are showing up anyway (empty)

"No image selected" needs styling

This:

Should look like this:

Looks like it's a CSS specificity issue. The placeholder has the .placeholder class applied, but the placeholder style is actually more specific than that:

.customize-control .attachment-media-view .placeholder,
.customize-control-header .placeholder

Attached image preview flash

When previewing an attachment image in the widget preview and the selected size is not the full size, there is a flash of the selected image before the full attachment object has loaded and the image is replaced with its full size.

Should we wait showing a preview of the image until the attachment object has loaded?
Should the image size in the preview be a medium, like the default widget image size, rather than full?

Image doesn't sit within widget container

Just tried this new Image Widget on a custom theme, Twenty Seventeen and also on Twenty Twelve and got the same result after adding an image. The image doesn't sit nicely in the actual widget.

Here's Twenty Twelve - https://cl.ly/3z0n3x0j0n15

Default image size to "medium"

Seems like it could be a better default size than full for the majority of themes.

Deleted Image from Media Library results in Broken Widget

Not certain if we should be proactive about this flow or not but the following results in a broken image widget:

Steps to Recreate

• Create a new Image Widget instance.
• Add a photo from the library, or upload a new item
• Save, verify all looks happy
• Open the media library, and permanently delete the image used in the widget

The Edit Image button still is shown in the widget editor, and selecting it results in:

On the front-end, it appears only the image title is rendered, which is good, but should we not render anything when there is no image to show?

Button text can go over the button

In different languages words can be longer. In Finnish button text go over the button.

Pre-populate URL field with existing URL selected when opening embed frame

In the case where a user enters a URL to embed instead of selecting an attachment, it would probably also be desirable for the user if the URL they entered were pre-populated into the URL field for embedding:

We do this presently for attachments, passing the selectedAttachment as the selection to show in the attachments browser sidebar.

• Also, if a url was selected, then the “Insert from URL” should be the initial frame not the browser..

See also #75.

Image widget buttons and flexbox

A few issues quickly discussed on Slack about buttons and flexbox, maybe something to consider:

• the image widget buttons use flexbox; while the Customizer has dropped support for old IEs, the widgets screen hasn't
• it would be the first time flexbox is used in core (by core I mean not the customizer), maybe this should be discussed with the project leads, namely Helen 🙂
• longer translations of the buttons may break everything, see screenshot below (flex-wrap: wrap plus some adjustments could help here but I'm not sure that would be the desired effect)

See also https://core.trac.wordpress.org/ticket/40220

JS coding standards

I'd recommend a general review before merging in core.

Minor things like spaces around arguments have patterns to follow clearly explained here:
https://make.wordpress.org/core/handbook/best-practices/coding-standards/javascript/#arrays-and-function-calls

Ideally, all these things (and more) should be addressed to avoid introducing even more inconsistencies in core.

Documentation:
https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/javascript/

While not explicitly mentioned, for analogy with PHP standards there should be a proper alignment, for example for the @param type, name, and description. Example from the current code:

* @param {wp.media.view.MediaFrame.Select} mediaFrame Select frame.
* @param {object} attachment Attachment object.

should be

* @param {wp.media.view.MediaFrame.Select} mediaFrame Select frame.
* @param {object}                          attachment Attachment object.

I'd also argue that wp.media.view.MediaFrame.Select is not a JS type :) I know this is common practice but IMHO should indicate just the proper JS type and wp.media.view.MediaFrame.Select should go in the description.

One more example:

* @param {Object}         options - Options.
* @param {Backbone.Model} options.model - Model.
* @param {jQuery}         options.el - Control container element.

here the alignment is a bit better, I wouldn't know what the - hyphen represents, and descriptions should be aligned. Same consideration for the type.

One more example, here the alignment looks good but I wouldn't know what the square brackets around param names are:

 * @param {string|Object} key       Attribute name or attribute pairs.
 * @param {mixed|Object}  [val]     Attribute value or options object.
 * @param {Object}        [options] Options when attribute name and value are passed separately.

Poster Image not Cleared on Video Change

When changing a video from an external url ( i.e. YouTube ) and selecting a video file from the media library instead, the old poster image from the YouTube video is persisted and still shown.

Steps to Recreate

• Add a new video widget
• Set the URL to a YouTube video
• Confirm the poster image is shown in the renderPreview
• Click "Change Video"
• Select a video file from the media library
• Note in the renderPreview the old poster image is shown from the YouTube video, but if you click play, the video file from the library is properly set.

Implement gallery widget

Gallery Widget Flow

See https://core.trac.wordpress.org/ticket/41914

Try to remove/deactivate media states instead of overriding createStates in subclasses

See #105 (review)

Allow adding media by external URL

Add the menu so media can be added via URL.

See https://core.trac.wordpress.org/ticket/32417#comment:69

Handle height/width for videos

There is no height or width fields when selecting or editing a video in the media manager. This is a challenge. The video shortcode defaults the width to 640 and the height as 360. When MediaElement.js initializes, it resizes the video to fit inside of its container scaled, but if MediaElement.js is disabled to let the browser natively render the video player (via plugin add_filter( 'wp_video_shortcode_library', '__return_empty_string' );), the widget overflows the container:

If a max-width:100% is hacked onto the video container element, and the height attribute is removed as follows:

diff --git a/wp-includes/widgets/class-wp-widget-media-video.php b/wp-includes/widgets/class-wp-widget-media-video.php
index f772817..dfc82f7 100644
--- a/wp-includes/widgets/class-wp-widget-media-video.php
+++ b/wp-includes/widgets/class-wp-widget-media-video.php
@@ -135,6 +135,8 @@ class WP_Widget_Media_Video extends WP_Widget_Media {
 			return;
 		}
 
+		add_filter( 'wp_video_shortcode', array( $this, 'inject_video_max_width_style' ) );
+
 		echo wp_video_shortcode(
 			array_merge(
 				$instance,
@@ -142,6 +144,20 @@ class WP_Widget_Media_Video extends WP_Widget_Media {
 			),
 			$instance['content']
 		);
+
+		remove_filter( 'wp_video_shortcode', array( $this, 'inject_video_max_width_style' ) );
+	}
+
+	/**
+	 * Inject max-width and remove height.
+	 *
+	 * @param string $html Video shortcode HTML output.
+	 * @returns string HTML Output.
+	 */
+	public function inject_video_max_width_style( $html ) {
+		$html = preg_replace( '/\bheight="\d+"/', '', $html );
+		$html = str_replace( 'style="', 'style="max-width:100%;', $html );
+		return $html;
 	}
 
 	/**

The result is better for the native video element:

However, when MediaElement.js is re-enabled then the video displayed shorter than the native player:

Upon playing, however, it then resizes dynamically to have the proper height for the video.

Open link in a new tab checkbox

It would be nice if there was an Open link in a new tab checkbox on the Select Image dialog rather than having to select an image and then edit the image, just to select this checkbox. It makes for a cumbersome user experience.

i.e. on this screen: https://cl.ly/0I3l1U1a0l1n

Set video media source automatically

This may be out of the scope for media widgets, but when using an audio or video file, the edit screen allows users to upload and select alternative sources for full html5 availability.

In the case of video, when selecting a mp4 or ogv or webm file, we could automatically set those as alternative sources.

This might not make a difference to the html5 compatibility, but it's one less thing a user has to worry about.

Add button to edit media attributes in appropriate modal

Upon selecting a media item, there should be a button that appears for changing the media:

Clicking the item should open the relevant modal for editing that media item's attributes:

See more at https://core.trac.wordpress.org/ticket/32417#comment:136

Make WP_Widget_Media::get_instance_schema() public

Currently the WP_Widget_Media::get_instance_schema() method is protected for the sake of:

This is protected because it may become part of WP_Widget eventually.

See #35574 (Add REST API JSON schema information to WP_Widget).

The idea was that it could be made protected while we wait for #35574 to land. Nevertheless, if that ticket results in get_instance_schema becoming public then any existing media widget extensions in plugins which retain protected visibility will then fatal error, which can be seen here: https://3v4l.org/j6emh

So I think we should just go ahead and make it public now, especially if we can validate that #35574 is indeed desired and should become part of WP_Widget itself.

Update oEmbed previews to use oembed/1.0/proxy endpoint

Update oEmbed previews once #40450 lands to use oEmbed proxy endpoint, though core would likely make use of it as well (so plugin may continue with noembed.com polyfill). See https://github.com/xwp/wordpress-develop/pull/225

Implement slideshow widget

More details tba.

Replace Button Clickable When No Item Selected

When editing an existing media widget ( Audio, Image, or Video ) you have the option to 'Replace' the existing asset. The ability to replace in this flow is under question in #100 - but there is also a bug in the replace flow.

When using the 'Replace' functionality in any of the widgets, the Replace button is always active, even when a media item is not selected. Clicking on the Replace button without an item selected results in error being thrown:

Video

Audio

Image

It appears these issues might actually be in underlying core media files... but at the very least, the Replace button should not be enabled unless a new media item is selected.

Apply clearfix for all themes

For the issue identified in #13 (comment) for Twenty Sixteen and fixed in #30 with regards to alignleft and alignright causing images widgets to corrupt layouts of sidebars, I think that the clearfix fix should probably be applied by the image widget itself for all themes. I imagine there are many themes that don't anticipate widgets to be floating their contents in this way and so not implement clearfix.

Remove autoplay setting from audio and video widgets

Everyone hates autoplay. :) Let's remove it from the default widget options.

Ensure widget is still registered at running hook

Since hooks are added in the constructor (not ideal) when the hook runs it should ideally check to make sure the widget is still enqueued.

Widget Organization & Class Structure

Since all media controls will have a shared set of code (and UI) to handle the media modal and the widget frame (title, caption, filters, etc.), there should be a parent class with the base functionality and child classes for the specific widgets. This would largely echo the way that customize controls work. I'm not sure if this is currently possible with widgets, but it would seem like a prerequisite for building separate image/video/audio/document widgets to me. Duplicating that baseline media code seems like a no-go.

I also wonder whether building these as separate widgets could actually cause more issues in a block-based system, where these widgets have to be merged with shortcodes and new blocks if all of these things come together. That could cause major backwards-compatibility issues within the next few months. This also relates to a comment I brought up in the context of editor blocks: when adding a media-type block, any type of media would likely bring up the existing media modal, at which point a more specific type of media could be selected. Or, even better, you could upload (or select) any type of file, then when you insert it it becomes a more specific type of block automatically. Rather than having to select the exact type of content from a much larger list of blocks, it's done automatically, which becomes particularly useful once you get into types of files that we may not be thinking about, starting with PDFs or .zips and extending to a very broad array of potential file types. It also seems to align with the core philosophies of striving for simplicity and decisions, not options. That approach can and should be balanced with discoverability but I doubt that making users select very-specific block types from the beginning is the best approach (and that doesn't necessarily mean that there couldn't also be a distinct image block that's tied into the more generic functionality - these are all questions that need to be researched).

All of that to say, if we want to launch something in the very near future as a quick win, we should go back to the more flexible media widget case, and constrain functionality where it makes sense for now. If we're looking for a more forward-thinking or longer-term approach, we should probably work out the best actual block-based solution rather than coming up with a set of interim widgets that could cause more problems than they solve.

Reordering widgets lost image preview in control

I reordered my widgets a couple times and then realized my preview disappeared.

Proposal: Rename WP_Widget_{Type} PHP classes to WP_Widget_Media_{Type}

We are using media_ as the ID base prefix for the media widgets, but while the Image widget has media_image as its ID base the current class name is WP_Widget_Image. For consistency sake, it would make sense if we renamed it to WP_Widget_Media_Image.