[wp-trac] [WordPress Trac] #21483: Refactor Customizer Upload, Image, and Background Image controls to leverage the media library/modal

[WordPress Trac]

#21483: Refactor Customizer Upload, Image, and Background Image controls to
leverage the media library/modal
-------------------------------------+-----------------------------
 Reporter:  jjonesftw                |       Owner:
     Type:  enhancement              |      Status:  new
 Priority:  normal                   |   Milestone:  4.1
Component:  Customize                |     Version:  3.5
 Severity:  normal                   |  Resolution:
 Keywords:  has-patch needs-testing  |     Focuses:  ui, javascript
-------------------------------------+-----------------------------
Changes (by celloexpressions):

 * keywords:  needs-patch => has-patch needs-testing
 * milestone:  Future Release => 4.1


Comment:

 Let's do this.

 [attachment:21483.diff] contains a rough first-pass at re-imagining the
 core media controls to leverage the media library. Some notes:
 - The JS is based off of @mattwiebe's [https://github.com/mattwiebe
 /advanced-upload-control Advanced Upload Control project], although I've
 started making extensive changes.
 - The goal for this ticket is to make these core controls as good as they
 can be in a backwards-compatible way. This means that, unfortunately, we
 cannot change what data is saved in the settings associated with these
 controls. Therefore, we have to stick with only grabbing the media file's
 URL from the media library. We'll do more exciting things in #29215.
 - For now, I've removed the concept of previously-uploaded files; with
 access to the media library, and because we don't have "multiple" support
 (like header images do, with the randomize option), the extra UI doesn't
 seem necessary at this point. The exception may be background images,
 although I'd argue that it isn't necessary, as they're accessible and
 searchable in the library.
 - Don't waste screen real estate for a small file-upload dropzone; while
 opening the library first is an extra step, there's a full-screen dropzone
 as soon as it's open.
 - Still need to implement a strategy for the default background image (and
 add handling for any of these controls that have default setting values).
 There's a lot of theme inconsistency here, as many (most?) themes that
 support custom backgrounds also set the background in CSS, making it
 impossible to remove the default background. Maybe remove should just be
 "default" for those? I tried checking what the backgrounds admin page does
 but, well, it's just a complete mess.
 - There's an awesome amount of red happening here. Unfortunately, most of
 it will probably need to be brought back for back-compat. Initial patch
 does that to demonstrate the advantages of leveraging the new code; it's
 really fairly straightforward. The biggest back-compat issues are with
 sub-classes, and there are a lot of these in the wild (particularly with
 `WP_Customize_Image_Control`). We'll need to get creative here.

 Things that the patch still needs to address:
 - How should generic-upload-control files be previewed in the Customizer
 controls area? There's probably something we can leverage from elsewhere
 in core. This would be things like audio/video, images, or other document
 types that need to be linked but can get an icon. Note that we can't
 display the document's title since we can only save the URL for back-
 compat reasons, unless we set it in the control from JS when inserting,
 and use something like `attachment_url_to_post_id()` to grab the info in
 PHP on subsequent loads.
 - Handling of default setting values when "remove" is invoked, and whether
 to allow removing the default (setting to empty), or to just make it a
 "default" button instead of remove.
 - Consider making the button/media manager labels customizable parameters
 of the `WP_Customize_Upload_Control` class, which would also further
 reduce the need for duplicated code in subclasses.
 - JS Strings need to be internationalized.
 - Coding standards.
 - Structured inline docs.
 - Potential code cleanup, especially in JS.
 - Comprehensive back-compat audit. It's likely that we won't be able to
 mimic the "extensions" argument easily, but the media library's
 `mime_type` feature is much more useful for most cases anyway. We need to
 keep all of the class functions around, and just remove any calls to them
 in the least obtrusive way possible so that we can avoid breaking anything
 sub-classing these (in PHP and JS). I've removed all of these for now -
 we'll add them back in once we figure out the strategy here. We probably
 need to go beyond just avoiding fatal errors in subclasses to making
 things that used to work still work - an initial investigation revealed a
 LOT of subclasses of `WP_Customize_Image_Control` in the wild. We need to
 investigate this more thuroughly to determine the best approach here, as
 those would ideally also be able to benefit from the new improvements.
 Again, the goal here is to bring a better experience to all of the
 existing controls that are out there; it'll be challenging but I think we
 can do it.
 - Go through all media-related tickets in the Customize component, and
 determine whether they're still relevant once this change is made.

--
Ticket URL: <https://core.trac.wordpress.org/ticket/21483#comment:22>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform