Make WordPress Core

Tagged: media Toggle Comment Threads | Keyboard Shortcuts

  • Joe McGill 2:56 am on November 10, 2015 Permalink |
    Tags: , , media,   

    Responsive Images in WordPress 4.4 

    WordPress 4.4 will add native responsive image support by including srcset and sizes attributes to the image markup it generates. For background on this feature, read the merge proposal.

    How it works

    WordPress automatically creates several sizes of each image uploaded to the media library. By including the available sizes of an image into a srcset attribute, browsers can now choose to download the most appropriate size and ignore the others—potentially saving bandwidth and speeding up page load times in the process.

    To help browsers select the best image from the source set list, we also include a default sizes attribute that is equivalent to (max-width: {{image-width}}px) 100vw, {{image-width}}px. While this default will work out of the box for a majority of sites, themes should customize the default sizes attribute as needed using the wp_calculate_image_sizes filter.

    Note that for compatibility with existing markup, neither srcset nor sizes are added or modified if they already exist in content HTML.

    For a full overview of how srcset and sizes works, I suggest reading Responsive Images in Practice, by Eric Portis over at A List Apart.

    New functions and hooks

    To implement this feature, we’ve added the following new functions to WordPress:

    • wp_get_attachment_image_srcset() – Retrieves the value for an image attachment’s srcset attribute.
    • wp_calculate_image_srcset() – A helper function to calculate the image sources to include in a srcset attribute.
    • wp_get_attachment_image_sizes() – Creates a sizes attribute value for an image.
    • wp_calculate_image_sizes() – A helper function to create the sizes attribute for an image.
    • wp_make_content_images_responsive() – Filters img elements in post content to add srcset and sizes attributes. For more information about the use of a display filter, read this post.
    • wp_image_add_srcset_and_sizes() – Adds srcset and sizes attributes to an existing img element. Used by wp_make_content_images_responsive().

    As a safeguard against adding very large images to srcset attributes, we’ve included a max_srcset_image_width filter, which allows themes to set a maximum image width for images include in source set lists. The default value is 1600px.

    A new default image size

    A new default intermediate size, medium_large, has been added to better take advantage of responsive image support. The new size is 768px wide by default, with no height limit, and can be used like any other size available in WordPress. As it is a standard size, it will only be generated when new images are uploaded or sizes are regenerated with third party plugins.

    The medium_large size is not included in the UI when selecting an image to insert in posts, nor are we including UI to change the image size from the media settings page. However, developers can modify the width of this new size using the update_option() function, similar to any other default image size.

    Customizing responsive image markup

    To modify the default srcset and sizes attributes,  you should use the wp_calculate_image_srcset and wp_calculate_image_sizes filters, respectively.

    Overriding the srcset or sizes attributes for images not embedded in post content (e.g. post thumbnails, galleries, etc.), can be accomplished using the wp_get_attachment_image_attributes filter, similar to how other image attributes are modified.

    Additionally, you can create your own custom markup patterns by using wp_get_attachment_image_srcset() directly in your templates. Here is an example of how you could use this function to build an <img> element with a custom sizes attribute:

    $img_src = wp_get_attachment_image_url( $attachment_id, 'medium' );
    $img_srcset = wp_get_attachment_image_srcset( $attachment_id, 'medium' );
    <img src="<?php echo esc_url( $img_src ); ?>"
         srcset="<?php echo esc_attr( $img_srcset ); ?>"
         sizes="(max-width: 50em) 87vw, 680px" alt="A rad wolf">

    Final notes

    Users of the RICG Responsive Images Plugin should upgrade to version 3.0.0 now in order to be compatible with the functionality that included in WordPress 4.4.

    • Tomas Mackevicius 3:33 am on November 10, 2015 Permalink | Log in to Reply

      Can we say that from now on users will be encouraged to always include full sized image instead of one that fits the regular content width the best, like size Large?

      Another question is if this improvement will affect images in older posts that are already inserted with certain predefined width parameters.

      Thank you!

      • Joe McGill 4:38 am on November 10, 2015 Permalink | Log in to Reply

        Hi Tomas,

        Site authors will be able to include whichever size they feel is most appropriate, but now site visitors will get the benefit of downloading the best image source available to fit their needs, which could be larger or smaller, depending on their device capabilities.

    • David Chandra Purnama 4:10 am on November 10, 2015 Permalink | Log in to Reply

      in wp we have “hard-crop” (such as thumbnail size), or soft-crop (like medium large sizes) or my fav is using fixes width, and very tall height to keep the image as is (resize, no crop)

      so how do WP check this images? what images WP uses?

      I don’t want to display my image content as thumbnail, when it shouldn’t be cropped (?)
      thank you.

      • Joe McGill 4:39 am on November 10, 2015 Permalink | Log in to Reply

        Hi David,

        WordPress will only include images that match the same aspect ratio as the image in the ‘src’ attribute.

    • Monika 8:06 am on November 10, 2015 Permalink | Log in to Reply

      I’m using WP 4.4 and twenty sixteen on my testsite.
      *only developer plugins are active

      *for “responsive image tests” I ‘m using always the same image and upload it again.

      *my last test was this morning.

      If I insert an image with 300×199 in a post,

      I can find all large sizes in source => this doesn’t make sense too me.


      <img src="xx/media/2015/11/IMGP9685-300×199.jpg" alt="IMGP9685"
      width="300" height="199" class="aligncenter size-medium wp-image-750"
      srcset="xx/media/2015/11/IMGP9685-250×166.jpg 250w,
      xx/media/2015/11/IMGP9685-300×199.jpg 300w,
      xx/media/2015/11/IMGP9685-768×511.jpg 768w,
      xx/media/2015/11/IMGP9685-1024×681.jpg 1024w,
      xx/media/2015/11/IMGP9685.jpg 1029w" sizes="(max-width: 300px) 85vw, 300px"

      How can I avoid this?

      • Joe McGill 1:13 pm on November 10, 2015 Permalink | Log in to Reply

        Hi Monika,

        The larger sizes are included in the srcset attribute in order to account for screens with high density displays and only the most appropriate size will be used for any device, so this is the expected behavior. However, if you want to keep out all the large sized images from being included in your srcset attributes, you can filter the max_srcset_image_width, like this:

        function filter_max_srcset( $max_width, $size_array ) {
        if ( $size_array[0] === 300 ) {
        $max_width = 768;

        return $max_width;
        add_filter( 'max_srcset_image_width', 'filter_max_srcset', 10, 2 );

    • Mark-k 1:36 pm on November 10, 2015 Permalink | Log in to Reply

      To add to monica above, it seems like there is a missing option, a non responsive image. Lets say the image is a company logo and it should be displayed at exactly one size no matter what images WP generates for it an if it doesn’t stretch well on the screen.

      • Joe McGill 3:54 pm on November 10, 2015 Permalink | Log in to Reply

        Hi Mark,

        The responsive image markup should not change the display size of your image. Instead, it’s used to let the browser know which image source to use. For example, if you have a company logo that should be displayed at 300px wide, and you have a 300px version of the logo and a 600px version of the logo, you can identify both image sources in the `srcset` attribute and retina displays could use the 600px version so the logo looks crisp on all devices.


        • Mark-k 5:54 pm on November 10, 2015 Permalink | Log in to Reply

          The point is that for whatever reason I don’t want to use anything except for the full size image, what should I do then. Possible (but maybe invalid) scenario is the ability to save the full size image on my local pc. If I give the browser the option to select whatever image is being displayed, what would be the image saved?

          Another related question that came into my mind is by what criteria the images are added to srcset? Are those all the images for which there is an add_image_size or is there some selectivity?

        • Mark-k 6:08 pm on November 10, 2015 Permalink | Log in to Reply

          Maybe I have a better real life question. Once images are compressed into about a file size of 30k it is hard to get any real reduction in size just by using lower dimension without terminally reducing the quality of the details of the image. Therefor I do not want to suggest to the browser to get any image smaller then 30k even if it fits better because the price I pay in bandwidth is not worth the quality reduction, and I would prefer to avoid another hit on the server just because the resolution was changed when flipping the device without making enough display space for a much better image.

          • Joe McGill 10:35 pm on November 10, 2015 Permalink | Log in to Reply

            Hi Mark,

            There may be valid scenarios where you would not want this functionality, and if so, you are free to use the included filters to modify/remove the default behavior. That said, I would suggest spending a bit of time getting familiar with the benefits of responsive images and how they work before making that decision, because generally, the benefits to your users (and your bandwidth) should be worth it. For a primer on responsive images, check out this blog series: http://blog.cloudfour.com/responsive-images-101-definitions/


            • Mark-k 7:43 am on November 11, 2015 Permalink

              1. It is really annoying to get from core developers the attitude of “we know better then you so trust us”. In this case since I am following the whatwg mailing list I am quiet sure I am aware of this feature history and how it is intended to be used and what were the objections to it that created the picture element in the end as much as you.

              2. Unlike oEmbed and REST API this is not a new functionality developed on empty slate and it has an impact on the behavior of all existing sites, therefor you can’t just say “it is easy to do with a filter” which might be very true but joe shmo that will upgrade from 4.3 to 4.4 doesn’t know that he is supposed to write a filter to keep his site functioning exactly as before.

              3. So this is my suggestion
              a. have an option to control whether this feature is inactive
              b. on upgrade from 4.3 set the option to true

              This follows what was done for link management so I am sure there is some efficient pattern to use here.

              People that want to opt in can use a simple plugin that should be run only once to do that.

            • Joe McGill 1:08 pm on November 11, 2015 Permalink


              Thanks for the feedback. Comments are not generally the best forum for long explanations and I was attempting to acknowledge that you may have valid reasons for turning these off without a long technical explanation. I can see how it would have come across as condescending, which was not my goal.

              I’ll add that we did ask for community feedback regarding whether this feature should be turned on by default or if we should toggle it on via a site option and the majority of people thought we should turn it on by default.


    • Travis Northcutt 8:51 pm on November 10, 2015 Permalink | Log in to Reply

      First off, awesome! Thanks, RICG team, for making this happen.

      > The medium_large size is not included in the UI when selecting an image to insert in posts, nor are we including UI to change the image size from the media settings page. However, developers can modify the width of this new size using the update_option() function, similar to any other default image size.

      One thought on this: does this mean that if the width of medium_large is changed, there won’t be any indication of that change (save, of course, for the actual images being generated at a different size)? If so, I wonder if that might make debugging a tad difficult, since it could lead to inconsistent behavior (old images at 768px, new ones at ____px) without a clear reason as to why, without looking directly at the database (something many/most people won’t/can’t do).

      That’s certainly not an argument in favor of a UI to change this, and is admittedly an edge case, but I wanted to at least mention it in case it bears further discussion.

      • Joe McGill 10:27 pm on November 10, 2015 Permalink | Log in to Reply

        Hey Travis,

        Good thought. For that size to change, a developer would have to intentionally run `update_option()`. I think it would be rare when that happens unintentionally, or that a future developer couldn’t check the size through a `get_option()` call in order to debug the issue. However, if we find out that leaving the option out of the admin UI causes a large amount of issues, we can certainly add it later.

        • Joe
    • Morten Rand-Hendriksen 10:04 pm on November 10, 2015 Permalink | Log in to Reply

      Probably a dumb question:

      Is `wp_make_content_images_responsive()` applied to posts by default ensuring that existing posts will receive responsive images? Or am I just misunderstanding the function of this function?

      • Joe McGill 10:29 pm on November 10, 2015 Permalink | Log in to Reply

        Hi Morten,

        Sorry that the post wasn’t clear. The `wp_make_content_images_responsive()` function is automatically hooked to the `the_content` filter and will automatically apply responsive image markup to all posts by default, regardless of when they were originally published.


        • Morten Rand-Hendriksen 10:40 pm on November 10, 2015 Permalink | Log in to Reply

          OK. That’s what I suspected. So the purpose of the wp_make_content_images_responsive() function comes into play any time you want to apply the RICG markup to content that is not filtered through the_content then.

          • lamnt 8:19 am on November 11, 2015 Permalink | Log in to Reply

            I did installed RICG 3.0 on wordpress 4.3 but i don’t see it works. Is this compatible with these? I also check attributes in “the_content”, i don’t see the srcset, data-size or something like that of RICG.
            It seems doesn’t work filter and automatically apply responsive image.

    • Paal Joachim Romdahl 10:21 pm on November 10, 2015 Permalink | Log in to Reply

      Ehhh hmm not sure what to say here….
      How would this benefit the regular beginner user and designers?
      I am trying to grasp what your saying.
      If you could “dumb down” the language a bit that would help.

    • programmin 4:10 am on November 11, 2015 Permalink | Log in to Reply

      This is exciting news! I wonder if there are any good developer tools for testing through these, as the Firefox Inspector doesn’t seem to give any special preview to the srcset or sizes attributes, just shows a very long attribute text.
      Thanks for the good work :)

    • FolioVision 4:43 am on November 11, 2015 Permalink | Log in to Reply

      HI Joe,

      This is wonderful! How does the srcset and sizes for responsive images fit in with Retina? Should we expect full retina support any time soon?


      • Joe McGill 12:58 pm on November 11, 2015 Permalink | Log in to Reply

        Hi Alec,

        Browsers that support the `srcset` and `sizes` take into account the screen density when selecting an appropriate source, so this will provide full retina support as long as the original uploaded image was large enough to have the appropriate sizes created by WordPress.


    • Dwain Maralack 1:04 am on November 12, 2015 Permalink | Log in to Reply

      Well done for getting the feature wrapped up Team!

    • David Chandra Purnama 1:26 pm on November 13, 2015 Permalink | Log in to Reply

      thank you for the explanation.
      is there possible performance and compatibility issue for filtering content with this complex parser? (vs the benefit for default content filter)
      here’s my full thoughts for this feature to help explain my question:

      • Joe McGill 3:05 pm on November 14, 2015 Permalink | Log in to Reply

        Hi David,

        Great write up about your experience testing the feature. Thanks for sharing.

        From a performance point of view, filtering the content to add responsive image support adds a bit of overhead, but many times, I expect users to benefit by downloading smaller images than they would have normally—making the small overhead worthwhile.

        On the compatibility side, I’m sure there will be some issues to work out. For example, the Jetpack team is working right now to make sure that Photon is compatible with this feature. As issues come up during the next few weeks, we’ll work to address what we can.


    • klihelp 10:27 pm on November 20, 2015 Permalink | Log in to Reply


    • joost de keijzer 10:35 am on November 26, 2015 Permalink | Log in to Reply

      Hi, great feature!

      De srcset attribute doesn’t seem to be added by default to images in a gallery. Is this on purpose?

  • Joe McGill 1:57 pm on September 30, 2015 Permalink |
    Tags: media,   

    Responsive Images: Merge Proposal 

    The RICG WordPress Team is proposing a partial merge of the RICG Responsive Images plugin into core in version 4.4. Specifically, we are proposing to add native srcset and sizes support to WordPress (ticket #33641).


    As of today, the average web page currently weighs over 2 MB with the majority of those bytes being attributed to images. Screen density and display sizes continue to increase and site owners are including larger image assets to keep up, causing slower page load times for people on smaller/older devices and on slower/expensive network connections. We have the opportunity to make a huge impact on the ~25% of the web that runs on WordPress by adding responsive image support out of the box so sites can serve appropriate sizes images to all users.

    Project Background

    The initial plugin idea was conceived by Tim Evko and Chris Coyier in April of 2014 before becoming the basis for the official WordPress implementation from the Responsive Images Community Group last November. Since that time, the plugin has been downloaded over 40,000 times and is actively installed on over 10,000 WordPress sites. We’ve gotten input from many WP core committers during regular meetings in the #feature-respimg slack channel, and received guidance from Mat Marquis and other members of the RICG—including the same people who wrote and are implementing the responsive image HTML spec.

    Implementation details

    First off, the plugin does not add any UI or admin settings to core. 🙌

    The plugin adds srcset and sizes attributes to images by extending wp_get_attachment_image(), which includes all post_thumbnails, photo galleries, and any other images that use wp_get_attachment_image() to build the markup.

    For images embedded in post content, we have opted to add srcset and sizes using a display filter rather than writing those attributes directly to the database. You can read more about that change in our previous project update. We’ve improved the performance of the display filter and believe it’s acceptable, but are still working to improve it further.

    In all cases, we have chosen to make use of the native intermediate sizes functionality in core to create alternate image sources for our srcset attributes rather than adding additional image sizes specifically for our use. This includes any user defined image sizes as long as they are resized versions (i.e., soft crops) of the file defined in the src attribute. Themes and plugins can also filter the value of the srcset attribute through included filter hooks.

    For the sizes attribute, we have chosen to use sizes="(min-width: {img.width}px) {img.width}px, 100vw" as a sensible default. However, this default value can and should be filtered by themes to meet their layout needs.

    Based on community feedback, we are choosing not to include a polyfill for non-supporting browsers directly in core. However, we would recommend that themes make use of Picturefill in order to provide responsive image support to the broadest set of users.

    While the plugin also includes experimental image compression settings for the Imagick editor (ticket #33642), we are not proposing that those enhancements be included at this time.

    Housekeeping and next steps

    This is a proposal and is subject to revision based on your feedback. If you haven’t already tried out the plugin, please download and install it from WordPress.org. You can review the current code and leave feedback at the project’s GitHub repository or in #feature-respimg on Slack.

    Many thanks to @mike for shepherding the project during this release cycle and @azaozz for his performance and security feedback. We’ve reached out to the accessibility team and received no objections, and we have reached out to @drew who will review the docs once a core patch is ready.

    • Brad Touesnard 2:22 pm on September 30, 2015 Permalink | Log in to Reply


    • Bryan Hoffman 2:30 pm on September 30, 2015 Permalink | Log in to Reply

      Very exciting!

    • Morten Rand-Hendriksen 2:57 pm on September 30, 2015 Permalink | Log in to Reply

      WordPress moves the world forward.

    • Ahmad Awais 4:26 pm on September 30, 2015 Permalink | Log in to Reply

      Excited about this project.

    • Mauricio Gofas 8:17 pm on September 30, 2015 Permalink | Log in to Reply


    • WebberZone 8:42 am on October 1, 2015 Permalink | Log in to Reply

      +1 for integrating this into core

    • Nevis-1 3:05 pm on October 1, 2015 Permalink | Log in to Reply

      Sounds intriguing…you get my vote.

    • jeffreynolte 9:42 pm on October 1, 2015 Permalink | Log in to Reply

      +1 here as well

    • growdigital 8:36 am on October 2, 2015 Permalink | Log in to Reply

      Absolutely 100%ly.

    • wesleymcole 7:17 pm on October 2, 2015 Permalink | Log in to Reply

      100% on board with this.

    • rngala 9:40 pm on October 2, 2015 Permalink | Log in to Reply

      Yes Please!

    • Annette Voelckner 10:18 pm on October 2, 2015 Permalink | Log in to Reply

      Yeah, sooo excited.

    • thatgrrl 4:47 pm on October 6, 2015 Permalink | Log in to Reply

      I’m not a developer but I did use this plugin and would like to comment on my experience with it. The idea is great, however the plugin generates a lot of extra code and image sizes in the post itself. This ended up giving me a lot of broken links to fix when I had to move my site. Cleaning up all those dead links took ages. I also found my original image had the file name changed, an extra 1 was added. (I’m not sure if that was part of the problem I was having or something created by the Responsive Images plugin). Anyway, I hope this problem can be taken into account. Maybe the feature can be available or turned off when it is added to the core. I would use the plugin again but only if it does not generate all that extra image sizes code in the post.

      • Joe McGill 5:53 pm on October 6, 2015 Permalink | Log in to Reply

        Hi @thatgrrl,

        Sorry to hear you had issues after moving hosts. The implementation we’re suggesting for Core would add `srcset` and `sizes` attributes to images when they’re displayed on the front end, and would not add the additional markup to posts as you describe.

    • Schweinepriester 3:34 pm on October 8, 2015 Permalink | Log in to Reply


    • orenwolf 1:27 am on October 23, 2015 Permalink | Log in to Reply

      @joemcgill – how will this change affect image caching? Will we need to tell upstream caches to Vary: on different criteria to avoid serving images with the wrong sizes to visitors?

      • Joe McGill 11:49 am on October 23, 2015 Permalink | Log in to Reply

        This change shouldn’t affect caches since the base HTML will stay consistent between page loads. The difference for users will be which image source their browser decides to request from each image.

    • zabatonni 9:02 am on October 26, 2015 Permalink | Log in to Reply

      +1 already redesigning aspect ratios of used images

    • szabesz 6:26 pm on October 26, 2015 Permalink | Log in to Reply

      I’m not a big fun of srcset as the average Joe cannot deal with images properly anyway, they upload whatever they can and do not actually care about the (file) size of the image (not to mention its name). I wish the Imsanity plugin was merged to WordPress. Much more useful.

    • lukasdan 4:44 am on October 27, 2015 Permalink | Log in to Reply

      Hi Joe, Will it works/compatible if i have images storage in amazon S3 and serve by CDN? I’m using wp offload s3.

    • mantismamita 10:47 am on October 29, 2015 Permalink | Log in to Reply

      Yes Please!! I’m an avid user of RICG Responsive Images plugin and would love to see this merged into core.

    • Robey Lawrence 2:13 am on November 2, 2015 Permalink | Log in to Reply

      ** Happy Dance! **

    • momo-fr 3:05 pm on November 4, 2015 Permalink | Log in to Reply

      Nice… good job!

    • John Huebner 3:21 am on November 10, 2015 Permalink | Log in to Reply

      Will there be a way to disable this? I’m using something else on several of my client’s sites already and after looking at RICG I know that it will break these sites and not supply what is currently being supplied. I will need to disable this before I can update these sites.

      • Joe McGill 1:20 pm on November 10, 2015 Permalink | Log in to Reply

        Hi John,

        You can use the included filters to modify/remove the new `srcset` and `sizes` attributes using the included filter hooks. For a full explanation of what will be included, read this post.

        Additionally, I would encourage you to report any inconsistent behavior you’re seeing with the RICG plugin over at our GitHub repo or on the WP.org plugin forums. Thanks.


    • CodeFish 7:15 am on November 19, 2015 Permalink | Log in to Reply

      Absolutely awesome feature! Much wanted!

  • Joe McGill 2:05 pm on September 26, 2015 Permalink |
    Tags: media,   

    Responsive Images Feature Plugin Update 

    It’s been a busy week over in #feature-respimg world!

    We are now using a display filter on the_content to include responsive image markup, and are looking for feedback on the approach.

    Why filter on display?

    • The sizes attribute describes the intended layout of an image to a browser before the page has been rendered, so that it can choose the appropriate image source. Since the theme knows the layout best, it should be able to filter the sizes values—something that isn’t possible if we save markup within the post content.
    • Ensures future compatibility if the user changes their theme (especially if they regenerate thumbnails) or if WordPress makes changes to the way it handles layouts.
    • Allows us to avoid accounting for the editing of image markup in TinyMCE, including directly through source, or dragging to resize.
    • Extends responsive image support to existing posts. This is the most requested feature, and a display filter is the only way—aside from bulk-modifying user content in the database—to provide this type of backwards compatibility.


    This first run uses the logic:

    • Match all images in content that include the uploads directory in their path.
    • Attempt to get the id and size from the default class attributes WordPress adds and pass those to our functions for generating srcset and sizes.
    • If this doesn’t work, try matching the image src to image paths in attachment metadata.

    In our internal tests, the current filter added around 3ms per image, which will be offset in many contexts by the time saved not downloading larger than necessary image assets. That said, the performance is not ideal, and we’re working on improving it based on the conversation we had in our meeting yesterday.

    How you can help

    Please leave comments below or in #feature-respimg if you have feedback on the approach, suggestions for improving the filter, or if you test and can provide additional performance data.

    Come get involved! Our meeting each week is on Friday at 19:00UTC in #feature-respimg.

    • simonrcodrington 2:45 pm on September 26, 2015 Permalink | Log in to Reply

      Thanks for the update Joe. Do you have any info on how this would work in practice? As in now currently when you add images to your posts you choose the image size that will be used and that image is saved into the post_content.

      Going forward would users just specify an image and then when WordPress is about to display the image it generates the srcset so the correct size image is chosen? Would users all be able to manually set an to display at a set size?

      Basically it’s a secondary fleet that is just running through the content of the post and looking for images and trying to build its srcset?

      Really keen on support for better handling of images and I think the potential slowdown of running a second fikter is negligible considering the potential download size savings on font end :)

      Are there any other resources I can look at to see how this will all piece together or somewhere I can go to help with testing?

      Thanks mate!

      • simonrcodrington 2:51 pm on September 26, 2015 Permalink | Log in to Reply

        Sorry for the awful typos in my initial comment (I have no idea how to edit them). Mainly my comment was just clarifying how it’s all going to work and wondering if there was any way I could help :)

    • Joe McGill 3:47 pm on September 26, 2015 Permalink | Log in to Reply

      Hi Simon. In practice, nothing has changed about the way a user inserts images into posts. They can choose an image and select which size to insert and then we will dynamically add `srcset` and `sizes` attributes when those images are displayed.

      To see how this works, you can install the RICG Responsive Images plugin on your site and review the code in the GitHub repo for the project.

    • Shapeshifter 3 4:15 pm on September 26, 2015 Permalink | Log in to Reply

      Some current thoughts:

      During the past 3 1/2 yrs, I have gone through 12-15 different Themes (both free and commercial) using Featured Images and content excerpts as links to Individual Posts. In the beginning, I uploaded thumbnail size images of 240 x 240px thinking that was all I needed. As I progressed, I chose larger sizes up to my current choice of 1200px wide by 600-700px high. The constant effort of having to delete the older image, find a larger one, crop and then upload it to the server became a pain in the butt. I have been using the RICG Responsive Images Plugin since it first came out and am tickled-to-death that it is being added to core.

      As Microsoft is updating all of its software to be easily used on devices of all sizes (from large TV Monitors to Smart Phones), doesn’t it make the most sense to always upload a single Featured Image of 1200 pixels or Larger to any WordPress site, which then will have easy portability using this plugin when switching Themes?

    • pepe 8:13 pm on September 26, 2015 Permalink | Log in to Reply

      I’m using a similar approach (well, almost: instead of a filter I’m using [media-credit] and a modified shortcode) with my custom theme on my blog. The only workaround I’ve found regarding performance is very aggressive fragment caching. I’m very interested to replace this customized solution with a core feature (especially if it promises to be faster than my current implementation).

    • wildmice 2:04 am on November 19, 2015 Permalink | Log in to Reply

      I’m relieved to hear that this has been implemented as a filter and left to the discretion of the theme developer. I was afraid that it might break my existing implementation of the same functionality using Picturefill.js. Having learned how impossible it is to serve responsively selected image files inside columns of a multi-column layout when images are less than the full column width, i was pretty nervous of this new feature. So great to learn that it’s been done in a low-risk way that is entirely optional.

  • Joe McGill 10:21 pm on September 5, 2015 Permalink |
    Tags: , media, ,   

    Responsive Images Feature Plugin Update 

    Following up on our first official project update, here’s a brief status update to keep everyone informed about the progress we’ve made.


    • Released v2.4.0 early last week, fixing several bugs and adding a few filters (changelog). Please test on your sites and leave us feedback!
    • Created placeholder tickets for adding srcset and sizes support ( #33641 ) and improving the compression settings of Imagick ( #33642 ).
    • @jaspermdegroot is digging into the content filter approach to support responsive images for old posts. Performance tests and details on GitHub. Feedback appreciated!

    Next Steps

    We’re ready to create an initial patch candidate for core. We’ll be working on that over the next week, with a more detailed update at that time.

    Check out the logs from our last meeting and join us for the next one on Friday at 19:00 UTC in #feature-respimg.

    Questions? Please leave feedback below, or ask anytime in #feature-respimg.

  • Joe McGill 11:35 pm on August 25, 2015 Permalink |
    Tags: , media, respimg,   

    Update: Responsive Image Support for Core 

    The responsive image team has been meeting regularly for a while. After our meeting earlier this week, we realized that make/core needs an update on what’s been going on with the RICG (Responsive Images Community Group) feature plugin, as well as to request feedback on a few questions.

    Our meetings are in #feature-respimg each Friday at 1900 UTC, so please come and chat to give feedback or if you’re interested in helping out!


    Several years ago, a ragtag group of web professionals identified a need for new HTML markup which would allow developers to declare multiple sources for an image—allowing devices to select the image source that was most appropriate for its own capabilities. Fast forward to today and all major browsers have either implemented these new tools or currently have them under consideration for development.

    With that as background, the RICG has been working on an Official WordPress Feature Plugin™ to test the viability of adding responsive image support natively into WordPress. Specifically, our aim is to automatically add srcset (using w descriptors) and sizes attributes to the image markup generated by WordPress. According to the WordPress.org plugin directory, there are over 10k active installs, so we’ve definitely seen an interest in this functionality.

    There are two main pieces of functionality included in the plugin, which can be considered separately for inclusion in core:

    1. Logic for producing responsive image markup
    2. Advanced image compression (via ImageMagick)

    Responsive Image Markup

    There is a lot to consider when proposing a change to the way WordPress outputs image markup, so I want to be clear about some of our assumptions going in:

    • Responsive image support should be added ‘invisibly’ without introducing new settings for users to worry about.
    • WordPress, out of the box, should only deal with resolution switching, and not the art direction use case for now. In other words, we would not be adding any API or admin UI for outputting different cropped images at specific breakpoints. (For more information about use cases and all things related to responsive images, I’d recommend reading the terrific Responsive Image 101 series by Jason Grigsby).
    • Provide this functionality using default and available user-defined sizes (via add_image_size()) for source sets rather than creating an additional set of crops. This choice is based on early feedback from Nacin regarding file-count concerns on some shared hosts.
    • Provide filter hooks so theme/plugin authors can extend/override defaults.
    • All sizes of an image (i.e., _wp_attachment_metadata['sizes']) with the same aspect ratio are resized versions of the same image, not custom art directed crops. This assumption has been okay so far, but there may be be plugins that replace the default image sizes with art directed crops that maintain the same aspect ratio. We’ll need to determine how to handle these cases.

    Questions to Consider

    1. How should we handle markup embedded in post content?
      • Currently, we embed the srcset attribute directly into posts with sizes added as a data attribute to make it easier for theme authors to filter the sizes attribute later. It’s tricky to decide when it’s appropriate to add layout relative markup to the database, but WordPress is currently doing this to a certain extent by adding width/height attributes to images, so this may be the best solution for now.
      • Instead, a more elegant solution would be to filter the content on output. This would avoid saving layout markup in the database, and extend support to posts with images that were published before the feature became available. We have a proof of concept but are unsure if adding another filter to the_content is appropriate. Confirmation either way on this question would help us move forward.
    2. Should we support srcset and sizes in older browsers?
      • The plugin includes the picturefill.js polyfill, which provides support for older browsers, but would be a new dependency for core.
      • We could view srcset and sizes as a progressive enhancement and only provide support in WordPress for newer browsers. In that case, we could drop the polyfill and save WordPress an extra JS dependency. Note that this polyfill is written by the same people writing and implementing the spec. We consider it to be very reliable.
    3. Should we turn responsive image support on by default?
      • “Decisions not options.” We propose that responsive images are enabled by default in core, with filters provided for disabling or modifying the feature.
      • If core does not want responsive images enabled by default, they could be enabled through a current_theme_supports() flag. Themes would have to “opt-in” to the feature.

    Advanced Image Compression

    The second potential enhancement introduced through our plugin is an improvement to the default ImageMagick compression settings currently being used in core. RICG contributor Dave Newton has done great research on the best compression settings for ImageMagick, and included them as an opt-in option within the plugin.

    The updated settings are absolutely killer when there are sufficient CPU and memory resources on the host server. In our trials, file sizes have decreased by >50% compared to the default core settings.

    However, on limited servers, these new settings could cause problems. We are iterating on them to find the right balance between the file-size savings and the CPU resources required to process large files.

    Final Notes

    We need your help!

    New features need lots of feedback and testing. Help us test these enhancements by installing the latest version of the plugin from WordPress.org.

    Be sure to enable advanced image compression and tell us how it does with your setup so we can gather more feedback.

    If you know of plugins that heavily modify or interact with custom image sizes or art-directed crops, please leave a comment below so we can test it with this feature.

    Have thoughts on the questions above? Let us know in the comments!

    Want to get involved? We meet each week in #feature-respimg on Friday at 1900 UTC.

    • Ahmad Awais 1:08 am on August 26, 2015 Permalink | Log in to Reply

      Will join the next meeting. Let’s do it.

    • bravokeyl 1:58 am on August 26, 2015 Permalink | Log in to Reply

      It’s a good one , but is “ element getting traction from specifications ?

      • wilto 2:49 pm on August 26, 2015 Permalink | Log in to Reply

        Yes indeed! All of the markup patterns used by the plugin are part of the HTML Living Standard:

        While the plugin is using Picturefill for the sake of older browsers, all modern browser support this markup natively to some extent—current versions of Firefox and Chrome support it fully, while Safari and Microsoft Edge have partial support. Picturefill polyfills these features in a granular way, so anything that can work natively will, while anything without native support will be shimmed.

    • Robert Chapin 2:10 am on August 26, 2015 Permalink | Log in to Reply

      For the HiDPI Gravatars plugin, I’ve been referencing caniuse.com with the “Usage Relative” option selected. We really are at the point now where Internet Explorer 11 is the only significant browser without support for srcset. Decide accordingly. Is it really worth adding core bloat to support IE 11? Would it benefit anyone other than Surface users? Are the accessibility benefits for desktop just as easily acheived in Chrome?

      • Joe McGill 2:00 pm on August 26, 2015 Permalink | Log in to Reply

        This is almost true. As of today, Safari only supports `srcset` with x descriptors so the polyfill is still needed to support w descriptors and `sizes`. There are signs that the next version will include full support, but that is currently not the case.

    • Michael Arestad 2:21 am on August 26, 2015 Permalink | Log in to Reply

      > 2. Should we support srcset and sizes in older browsers?

      No. No need. this can gracefully degrade.

      > 3. Should we turn responsive image support on by default?

      This is definitely the hardest question and might answer itself during larger-scale testing. Going forward, it would make sense to unless it breaks a bunch of themes that do crop the attachment images (or do something else funky).

      • Joe McGill 2:07 pm on August 26, 2015 Permalink | Log in to Reply

        Thanks Michael,

        As a counter argument for supporting srcset and sizes in older browsers: with many older devices being in use around the world, I wonder if the addition of the polyfill—at just over 11kb minified—is worth the potential bandwidth savings that would be gained by potentially loading smaller image sources.

    • padams 6:25 am on August 26, 2015 Permalink | Log in to Reply

      Responsive images are probably not going to be very useful unless the theme itself has a responsive design. Did you guys think about making themes declare support for responsive images instead of making it a global on/off setting?

      • tevko 1:13 am on August 27, 2015 Permalink | Log in to Reply

        Hey padams, since we’re using the srcset attribute with sizes, responsive images will help regardless of fixed width or fluid designs. This is because the srcset / sizes combination works to deliver the best image size based on the users screen resolution and viewport width. This means that two different devices at the same width could get a different image, simply because their screen resolutions are different. This is great for the user because it means that their device will get the best looking image regardless of viewport size.

    • Monika 6:42 am on August 26, 2015 Permalink | Log in to Reply

      >> 3. Should we turn responsive image support on by default?

      >>>If core does not want responsive images enabled by default, they could be enabled through a current_theme_supports() flag. Themes would have to “opt-in” to the feature.

      yes please!

      1. RICG This plugin works by including all available image sizes for each image upload.

      Most of the time we don’t need “all” image sizes , thats why I preferr

      it is easier to use as RICG if I don’t want all image sizes

      Feedback: If I’m using: ‘advanced-image-compression

      my upload failes
      256php memory

    • kuzvac 7:11 am on August 26, 2015 Permalink | Log in to Reply

      Please use “picture” element instead of srcset! Picture element already have backward compatibility to older browsers. https://dev.opera.com/articles/native-responsive-images/
      And use cases https://dev.opera.com/articles/responsive-images/
      And progressive jpg, god, yes.

      • wilto 2:54 pm on August 26, 2015 Permalink | Log in to Reply

        For a “fully automated” situation like this one, we’re apt to get a much better result using `srcset`/`sizes`. `picture` is intended for “art direction” use cases, where there’s a need to set explicit and very specific breakpoints based on the viewport, with the image sources themselves varying slightly. All the `srcset` syntaxes, however, allow the browser to choose the best fit from a list of sources that are identical (apart from their dimensions). `srcset` factor’s in the user’s display density, the size of the image _in the layout_ (rather than based on the viewport), and soon additional factors like a user preference or a bandwidth cap. Since WP will be generating all the different cuts of an image, we end up with something completely seamless: smaller images for the user and no wall of breakpoint decisions for the image uploader.

        And no worries about backwards compatibility—that’s covered with `srcset` as well, either via Picturefill or via the old-fashioned `src` attribute on `img`.

    • Brad Touesnard 11:48 am on August 26, 2015 Permalink | Log in to Reply

      > 2. Should we support srcset and sizes in older browsers?

      I think by default they should not be supported in older browsers, but it should be easy to just install & activate an official plugin to enable them for older browsers.

      > 3. Should we turn responsive image support on by default?

      I suggested the `current_theme_supports()` flag on Slack. I think it should be up to the theme to turn on responsive image support. If the theme is designed for WordPress’ current image resizing it’s not very likely to work well with responsive images.

      I’d like to see the image compression stuff spun off into it’s own independent plugin. Is there a reason it is lumped in with the responsive image stuff?

      • tevko 1:31 am on August 27, 2015 Permalink | Log in to Reply

        Hey Brad, thanks for the feedback.

        Regarding your first point, seeing that RICG Responsive Images is the official plugin, and that plugin provides fallback support, it would seem natural to assume that if integrated into WP Core, fallback support would also be provided.

        Additionally, being an interfaceless plugin that runs behind the scenes, it wouldn’t be readily apparent to users that something else would need to be installed in order to provide fallback support. I think bundling a small polyfill in with the feature would make it easiest on all users. The ability to dequeue the polyfill also exists and has been documented here – https://github.com/ResponsiveImagesCG/wp-tevko-responsive-images#tevkori_get_srcset_string-id-size-

    • John Huebner 12:36 pm on August 26, 2015 Permalink | Log in to Reply

      > In other words, we would not be adding any API or admin UI for outputting different cropped images at specific breakpoints.

      Just my thoughts on this one aspect. While it would be great to have something built into WP automatically handle responsive images, without the ability to specify different images this will not be of much value in the work that I’m required to do. Using the automatically generated images will only be of use to the most generic users. I don’t think I have a single client that would be happy with this model, which is why I don’t use the plugin mentioned.

      • wilto 3:01 pm on August 26, 2015 Permalink | Log in to Reply

        We’re totally agreed that the “art direction” use case covered by the `picture` element—and the accompanying UI changes that would have to go into uploading images—is a valuable one. It’s in the planning stages now.

        However, just like you said, this _is_ a feature of use to the most generic users: anyone putting together a responsive theme that contains large images. If you’ve got visitors to your site using small viewports or low-density displays and you’ve got a theme that contains large or high-resolution images, adding this feature to core ensures that you’re not serving massive images to small viewports or high-density images to low-density displays—situations where the user will see no benefit, but be forced to incur an additional cost.

        It’s better to think of this as a behind-the-scenes enhancement to images, rather than a situation where your client will need to pick and choose breakpoints. Rolling out these features on FT.com resulted in a 66% reduction in image weight*. On my current project we’re looking at an ~80% reduction on 320px, low-density displays, without any changes to the uploader workflow.

    • Nicolas Juen 3:32 pm on August 26, 2015 Permalink | Log in to Reply

      I’m glad this feature is coming to the core, in my agency we are already using a custom solution for this consisting of this plugin (https://github.com/asadowski10/advanced-responsive-images) + WP_Thumb.
      The difference here is that the frontend developper is defining locations on json file, and associate image sizes + breakpoints wich are defined in one other file.
      Then on post_thumbnail function we call with one arg (data-location) with the location defined on json file. This allow us to handle multiple display cases, like in the slider, content, widget area etc.

      Is this conception have been tough ? Is this core functionnality will be hackable so we can do like this ?
      We are using picture fill too but it’s not compatible with lazyload, some libraries do and use the picture element, wich is pretty different from srcset.

    • Ricard Torres 8:18 pm on August 26, 2015 Permalink | Log in to Reply

      One of the top plugins out there that deals with images: https://wordpress.org/plugins/regenerate-thumbnails/

    • Phil Smart 11:57 pm on August 26, 2015 Permalink | Log in to Reply

      I’m just going to weight in quickly and say that I actually like the idea of what the Fusion guys are exploring with their plugin, Image Shortcake (http://fusion.net/story/144755/introducing-image-shortcake-v0-1-0/).

      Their basic approach is to add images to TinyMCE as shortcodes – instead of direct markup – giving them the flexibility to dynamically implement whatever specific markup they need.

      I know it’s a stepping a little deeper than straight up responsive image support, but storing images as shortcodes does seem to be a great starting point for then folding in (and easily updating) necessary markup.

    • Morten Rand-Hendriksen 5:14 pm on August 27, 2015 Permalink | Log in to Reply

      Quick answers:

      1. As you probably know from my blog posts, I am a proponent of the filter-on-output solution. For responsive images to work as effectively as the spec allows, theme and plugin devs have to be able to define the actual display sizes of images through variables. For that to work, the HTML output must be filtered based on current theme and plugins. This will cause some issues with caching services and CDNs, but I think that’s a minor concern. The one thing I hope can be avoided is the blanket approach of sizes=”100w, [original_image_size]”

      2. Backwards compatibility within reason is impoetatn because those that will benefit the most from this development (people on slow / low bandwidth / expensive connections and older devices) often use older browsers.

      3. Yes, turn it on by default. This should be invisible and transparent. We have a major opportunity here to use WordPress to push web standards forward, and that cannonly happen if we make some serious commitments like this.

      Great work to everyone who has been working on this. I am very excited about this plugin and its potential.

  • Nick Halsey 3:30 pm on July 16, 2015 Permalink
    Tags: , , , , media,   

    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.

    • Maria Antonietta Perna 4:50 pm on July 16, 2015 Permalink | Log in to Reply

      Great news! The WP Customizer keeps getting better and better.

    • Schwarttzy 5:15 pm on August 10, 2015 Permalink | Log in to Reply

      We should really create an easy to use sanitize function for “choices” so that only options in the list are able to be sanitized through. Instead of me writing a custom function for every single one that I want to do that on.

    • Peter Elmered 8:03 pm on August 12, 2015 Permalink | Log in to Reply

      Something seams to be wrong with the cropped-image control example. For me it generates the following error:

      Fatal error: Call to a member function check_capabilities() on null in /var/www/site/public/wp/wp-includes/class-wp-customize-control.php on line 283

      I use WordPress 4.3-RC2-33611

      • Peter Elmered 10:02 am on August 13, 2015 Permalink | Log in to Reply

        I managed to solve this, but how do I get the image that i cropped? I can see that the cropped image is created, but I can’t find any way to get the image URL for the cropped image from the returned ID.

        This code only gives me the standard thumbnail size, and not the cropped image:
        wp_get_attachment_image_src( absint( get_option( ‘cropped_image_setting’ ) ) )

        I can’t find anything that indicates support for this in /wp-inlucdes/media.php either.

    • smartpixels 3:55 pm on August 14, 2015 Permalink | Log in to Reply

      If you are using the Customizer JS API are we expected to use AJAX to get image URL’s if we are using the media control and storing ID’S and not URL’s

  • Ryan Boren 12:01 am on July 15, 2015 Permalink
    Tags: , bubbles, , content-overrun, , edit-site, , , media, , , network-admin, right-now, ,   

    Today in the Nightly: Site icons in the customizer, editor patterns, more accessible comment bubbles, row toggle focus styling 

    Install the nightly, and try out this fresh batch of shiny.

    Site Icons in the Customizer

    I’ve long wanted site icons in the customizer alongside site title and tagline. The identity information that I always want to edit when first setting up a site are now all together in the customizer.

    For more visuals, see these visual records.

    See #16434.

    Editor Patterns

    Create bulleted lists, ordered lists, and blockquotes using markdown like patterns. I find this particularly handy on phones when the editor toolbar is offscreen.

    Screen Shot 2015-07-14 at 4.39.12 PM

    See #31441.

    Better focus styling for list table row toggles

    See #32395.

    Better accessibility and design for the comments bubble

    The comments columns in our list tables were among the most confusing for screen reader users. Accessibility and visuals are now improved.

    See #32152.

    Eliminate content overruns on small screens

    An audit of content overruns on small screens resulted in many fixes.



    See #32846.

    Styling improvements on small screens for Right Now in the network admin

    See #32962.

    Improved header information in Network Admin Edit Site tabs

    • Use the site’s name rather than URL in the Edit Site header.
    • Provide “Visit” and “Dashboard” links for the site on all tabs.



    See #32525.

    Disambiguate “Automatically add new top-level pages to this menu”

    In the customizer, a menu’s auto-add pages option is now separated from the preceding menu location checkboxes.

    See #32820.

     Passwords UI Improvements

    Passwords received a couple of improvements. The show/hide toggles look better, and passwords ui is on the install screen. Passwords on the install screen still needs a little more flow work.

    See #32589 and #32925.

    For more visuals, see these visual records.

    Reduce link noise in media library list view

    This is visually subtle but removes confusion for screen readers.


    See #32254.


    Previously: Today in the Nightly: Customize in the Toolbar, Passwords UI, List Tables on Phones, Dashicons

  • Scott Taylor 9:54 pm on January 22, 2015 Permalink
    Tags: , , media   

    The Case for JS Modules 

    I originally posted some of this content here: Split javascript files in media into modules

    The patch on that ticket breaks up the Backbone classes in media-models.js, media-views.js, media-audiovideo.js, and media-grid.js into modules and injects them via Browserify on build/watch into a built file. Let’s start at the beginning.

    Brain overload

    Files that are 1000s of lines long are hard to consume. We try to alleviate this by adding copious amounts of docs. Still, it’s a lot to look at. Ideally, we would break our files into smaller modules and then somehow join them together in a build process.

    It is common practice to serve (sometimes very large) minified files for JS and CSS that have concatenated many smaller files together and uglify’d (minified/obfuscated) them. It is no longer common or best practice to develop with huge files. We can learn a lot from emerging front end development trends, especially those from the Node/NPM community. In some cases, we can even share code.

    We’ll use Media as the main culprit, but this could apply to any “manifest” – a term I use to describe files that contain the entire public API for a feature. Something like media-views.js, it might be nice to bounce from view to view in the same file, provided you know exactly what you are looking at, what depends on what, etc.

    I have found, it is completely overwhelming for almost everyone. It would be great if each discreet piece could be viewed in isolation with its dependencies clearly stated.

    There are many ways to accomplish the splitting of large files. I want to focus on 2 of the most common.


    Backbone is one of a growing number of MV* frameworks for JavaScript. A large majority of the code related to media either belongs to a handful of Models or to the increasingly large library of Views and View Templates.

    Views are the building blocks for the presentation of Media (you know, “the Media Modal” or 4.0’s “Media Grid”).

    The main canvas on which these Views are stitched together are called Frames, which are themselves Views – tilting our use of Backbone more towards MVP, P standing for Presenter.

    We have Controllers, which are called States, but they belong to a Frame (Presenter! also a View!), so anyways…. for now….

    When we create new UIs, we are more than likely adding new Views/Templates, or updating existing Views.

    If we wanted to move from one large file to many files that each contain a class, we would create Modules.

    Grunt is a task runner. We use Grunt to build our src directory into our build directory.


    Require is a great tool for converting AMD modules into built files. Require leans on Dependency Injection in its syntax:

    ], function (Taco, Burrito, Meal) {
        var Dinner = Meal.extend({
            // taco-related code
        return Dinner;

    This syntax works great, unless you have way more dependencies. Refactoring code could unwind a module that has a lot of dependencies, but if you are just trying to convert legacy classes into a module, Require starts to get a little weird. Concrete example: Frames have a TON of dependencies.

    Require becomes a Grunt task to make one big file by recursing the dependency tree in an initial manifest. Require, by default, loads JS asynchronously, which can cause race conditions with plugins or themes that expect code to be registered on $(document).ready() or window.onload.

    Require works even if you don’t build via Grunt.


    Browserify is a tool that allows you to use Node-style modules and run them in a browser without changing from the Node syntax. Browserify requires a build for this to work.

    Using our example from above, this is the syntax for Browserify:

    var Taco = require( './models/taco.js' ),
        Burrito = require( './models/burrito.js' ),
        Meal = require( './controllers/meal.js' ),
    Dinner = Meal.extend({
        // taco-related code
    module.exports = Dinner;

    Browserify leans more towards the Service Locator pattern.

    Browserify scans the abstract syntax tree (AST) of your JS code to compile dependencies. Your modules themselves get wrapped in their own scope like so:

    (function (require, module, exports) { 

    After spending a lot of time messing around with both: I think we should use Browserify.

    Converting “Legacy” Code

    The media JS code is some of the most “modern” code in WordPress, but it still clunkily lives in huge files. To convert the code into modules, we need to make a lot of individual files (one for each Backbone class).

    We also need to make sure we maintain the existing wp.media namespaces for backwards compatibility. We don’t want any existing functionality to change, we just want to build the files differently.

    Even though the code is defined differently, wrapped in a new scope, and looks different when “built”, we can still maintain our current API design: what is publicly accessible now will remain publicly accessible.

    In the patch

    Disclaimer: this patch is for experimentation only. It will go stale probably before this post is published. It works, but it is only a playground for now. If this moves forward, it will be a laborious Subversion process to create a bunch of new files.

    I have added a folder to wp-includes/js, media, that contains the modules and the built manifests. My patch adjusts script-loader.php to use these new paths.

    media contains the following files/folders:

    views/ (with another round of subfolders)

    The build pipeline

    If you are following along with that patch and want to see this in action, run in the project root:

    npm install

    Afterwards, run:

    grunt watch

    *.manifest.js files get built into *.js files when you change a file in media/*, provided you are running the grunt watch task. The watcher will automatically call browserify:media and uglify:media when those files change. This allows you to run your site from src or build, and you will still get Browserify’d files. SCRIPT_DEBUG will either run *.js or *.min.js, just like any other minified JS in core.

    This is a proposal

    I would like to hear feedback from the overall community and certainly from our fair share of JS-trained ninjas. A common reason to *not* do something like this is the barrier to entry for new developers. I would argue in this case that the code becomes MORE readable and understandable. I was shocked myself to see how much simpler it was to absorb one piece at a time once the code was laid out in modules.

    • deltafactory 10:07 pm on January 22, 2015 Permalink | Log in to Reply

      As someone who was trying to wrap my head around wp.media as recently as yesterday (with little success), I strongly support this from a development and maintenance perspective.

      • Primoz Cigler 6:12 pm on January 23, 2015 Permalink | Log in to Reply


        I attempted several times to ‘load’ these enormous JS files to my brain in last few months. Every time with little to no success. As I am using RequireJS I would be more font of the later, but I absolutely agree with your foreseen troubles it would bring. So browserify + grunt it is, hurray!

    • Daniel Bachhuber 10:13 pm on January 22, 2015 Permalink | Log in to Reply

      I strongly support breaking apart our JavaScript. Browserify has become a new standard for the projects I’ve been working on.

    • Luis Rodrigues 10:22 pm on January 22, 2015 Permalink | Log in to Reply

      I for one applaud this initiative. There may be a couple of extra hoops to jump through, but they become virtually irrelevant with a properly configured Gruntfile to handle watching and building modules into the project.

      Big fan of Browserify, too. Browserify will handle AMD modules if you need them (using plugins like `deamdify`) and coexists with non-module dependencies much, much better than RequireJS. (Last time I got RequireJS and WP to work together, I had to mess with WP’s enqueue mechanism because the loader is rather sensitive to scripts that alter the DOM.)

    • K.Adam White 10:28 pm on January 22, 2015 Permalink | Log in to Reply

      Music to my ears, @wonderboymusic! Regarding the “barrier to entry” argument, in my experience the biggest barrier I’ve seen people hit while working with modules has been that in almost all circumstances, the complexity of setup and configuration required by a system like Require results in a front-loaded learning curve. Coming onto an existing project with a modular system is, by point of contrast, generally a pleasant experience because it is much more obvious where any particular piece of code lives.

      I’d throw in my $0.02 that since we’d need a build process anyway to ship production files, we should optimize for ease of development: whichever system requires the least work when adding a file. Webpack’s a good build tool that we’ve been using which supports both AMD and Node-style modules, as well.

    • Solinx 10:41 pm on January 22, 2015 Permalink | Log in to Reply

      Like K. Adam I found that working with modules does increase the initial barrier a bit for developers who rarely use javascript, but certainly not by much. And once the required code to work with modules is understood it makes things easier due to the clear structure and focussed content of each module.

      Currently we use AMD (require.js) and build our combined js file with Almond, but we’re strongly considering to switch to Browserify or Bower. AMD isn’t as widely supported by packages as we’d like, and Require.js appears to clash with our new general purpose build tool, Gulp.js.

    • Mike Schinkel 11:14 pm on January 22, 2015 Permalink | Log in to Reply

      I have nothing but support for this proposal. Great work!

    • faction23 1:09 am on January 23, 2015 Permalink | Log in to Reply

      Having the js broken up into modules will be great! Have you tested/considered your third option, the use of native es6 modules and then something like webpack with the 6to5 loader (es 6 to 5 transpiler)? es6 modules are finalized since last august – es6 was fully feature frozen then -and I’ve been working with 6to5 for a little bit and its rock solid. The main reason would be longer term viability. es6 modules are going to be here to stay guaranteed, plus they pretty well supersede common/amd modules…

    • Mike Schroder 1:41 am on January 23, 2015 Permalink | Log in to Reply

      This sounds most excellent.

      Thanks for putting this together!

    • Helen Hou-Sandi 4:06 pm on January 23, 2015 Permalink | Log in to Reply

      Really looking forward to some sanity in this area. Concerns I typically have about barrier to entry are mostly irrelevant here – components such as media already require a high level of understanding and some amount of experience, which makes familiarity with build tools as a requirement of development much more likely. As I’m understanding the proposal, build/watch won’t be needed if you don’t touch any involved JS.

    • Aaron Jorbin 8:42 pm on January 23, 2015 Permalink | Log in to Reply

      My concerns are the same as others, that this increases the barrier to entry. I think that as long as some documention get’s written for the core handbook that we can also reference and point to about how and why (with this post serving as a great foundation).

      One thing we will want to consider, if a file like wp-includes/js/media/models.js is going to be a generated file, we should exclude it from jshint.

    • Ben Doherty (Oomph, Inc) 12:42 am on January 25, 2015 Permalink | Log in to Reply

      You have my +1 in this effort. The media-* files are just too much to wrap one’s head around effectively, and in general we are in dire need of organization and better documentation for the entire Media Manager API so that developers can write better integrations. I don’t believe there will be much increase in barrier-to-entry by splitting these files up. As Helen said, developers who dig into this are likely to already be familiar with the build toolchain, but may not need even it when using the files for reference.

    • nikeo 3:04 pm on January 25, 2015 Permalink | Log in to Reply

      +1. Those types of workflows + tools have to be democratized. I don’t think there will be much increas in barrier-to-entry as well.

    • lmartins 10:16 pm on January 25, 2015 Permalink | Log in to Reply

      Common JS with Browserify or similar every time. Any front-end person deals with them these days, so I imagine quite accessible to any dev.

    • Per Soderlind 11:13 am on January 28, 2015 Permalink | Log in to Reply

      + 1, understanding (your) wp.media code today is hard.

    • Andrew Ozz 6:07 pm on February 2, 2015 Permalink | Log in to Reply

      Don’t think this is going to make huge difference. Generally whether you edit few places in a single file or have to open and edit several files doesn’t make a difference. Your IDE should handle both cases transparently :) However agree that it is better to have a nice file structure that somewhat matches the JS structure.

      In my mind it is more important to improve/fix the “JS structure”, i.e. this:

      The main canvas on which these Views are stitched together are called Frames, which are themselves Views – tilting our use of Backbone more towards MVP, P standing for Presenter.

      We have Controllers, which are called States, but they belong to a Frame (Presenter! also a View!), so anyways…. for now….

      I’m hoping we will get that opportunity when implementing the image flow changes.

    • Dwain Maralack 9:25 pm on February 8, 2015 Permalink | Log in to Reply

      +1 for a more logical file structure. Most of the files here will most probably only be changed by experienced / core dev’s so the barrier to entry is not a major concern. The entry barrier can easily be solved by supporting documentation.

  • Eric Andrew Lewis 1:39 am on June 28, 2014 Permalink
    Tags: , media   

    Media Grid Update 

    Media Grid started as a standalone plugin by Shaun Andrews, which was a reimagining of the UI as an alternative to the traditional post list view in the Media Library. The argument was that images are the ubiquitous media type in most users’ libraries, so we should provide an interface to browse media visually.

    I joined the project in late April, attempting to integrate existing Media modal code. This work was merged into the standalone plugin, and into trunk(see #24716) in early June. In the process, I created documentation for the Media code, which is the most comprehensive resource for untangling the Backbone wires in media.

    Questions were raised about what problem the grid was solving, so in order to get a more hands-on understanding of user engagement with the Media Library, Jerry Bates performed user interviews. These confirmed our assumption that images are the pervasive media type, but also surfaced the fact that users identify media in different ways – some by the thumbnail, some by what post a media item is uploaded to, some by title.

    After a good amount of UX/UI chatter in weekly meetings, we decided we could serve users better by making a few changes to the original implementation merged into trunk. We’ve landed on mock-ups for a quick pivot, which I’m working on implementing . I’ll be dropping diffs for y’all Javascript Jedis to peruse on #24716, feedback welcome and appreciated. I hope to have merge-ables by Monday morning, and then to progress to user testing.

  • Eric Andrew Lewis 3:50 pm on May 29, 2014 Permalink
    Tags: media   

    Media component office hours 

    Weekly office hours (bug scrubbing and feature development chat) for the Media component will start tomorrow, combining with Media Grid’s weekly meeting.

    I’ve heard the Media component is “where tickets on trac go to die,” let’s see what we can do to thwart that status quo.

    Our Media Grid meetings have been held every Friday at 1700 UTC in #wordpress-ui. We’ll keep the same time, but move the meeting into #wordpress-dev.

compose new post
next post/next comment
previous post/previous comment
show/hide comments
go to top
go to login
show/hide help
shift + esc
Skip to toolbar