Notes on the WordPress 3.5 Media Uploader

I am currently beta-testing the upcoming WordPress 3.5 release (scheduled for December).

One of the major features of the new release is the new and improved media management, deeply redesigned under the leadership of Daryl Koopersmith (@koop). In the words of lead developer Andrew Nacin:

The biggest thing we’ve been working on is overhauling the media experience from the ground up. We’ve made it all fair game: How you upload photos, arrange galleries, insert images into posts, and more. It’s still rough around the edges and some pieces are missing — which means now is the perfect time to test it out, report issues, and help shape our headline feature.

I am really welcoming those changes, as the media management interface in WP was lagging behind other publishing platforms (thinking of the Facebook image uploader, for instance).

On the other hand, such deep changes in essential functions need to be scrutinized with caution… In the past, I have been building some automated functionalities into my themes, which served as a stable workflow for building image galleries. I really hope that the 3.5 release will improve the workflow, and won’t break it.

Since this is a lenghty post, here is a Table of Contents:

The default gallery vs custom galleries

During this entire post, I will talk a lot about the “default gallery”. First of all, let’s get that terminology straight: in WordPress, images uploaded through the post editor are attached to that post. Even if they don’t show up on the front-end, the system knows that they have a direct relation with their “parent” post. If you place the [gallery] short code into your post, all the attached images will be displayed. That’s what I call the “default gallery”.

That post->attachment relation has allowed theme developers to craft “automated gallery” functions into their themes. “Automated” in the sense that any image attached to the post would automatically show up in the gallery, without any further action by the user. This also meant that in terms of layout, the gallery could be positioned independently from the textual post content: above the post, underneath the post, next to the post in a sidebar, etc.

Sidenote: if you are curious about the code used for auto-generating such galleries, have a look at this Digging-into-WordPress snippet that got me started, and at the imagebox or imagebox-array functions that I am currently using in my themes.

It’s a really powerful function, and fits perfectly into the “WordPress-as-a-CMS” way of thinking. Here are some examples of custom themes I have built, where the galleries are generated in that way. Those layouts wouldn’t be possible if the gallery had to be placed manually inside the post content area by the user.

Three examples of custom automated galleries

I find this method extremely useful for the following reasons:

  • The theme author has full control over the page layout.
  • The theme author has precise control over the html markup of the gallery, as well as the image-size (it can be other than “thumbnail”).
  • For the end user, the workflow is simplified.

Let’s focus a bit on the last point. When the theme auto-generates a gallery from the attached images, the end user workflow looks like this:

  1. Click the “Upload/Insert” button.
  2. Upload your attachments.
  3. If the order isn’t correct, change it by drag and drop.
  4. Click “Save all changes”, then close the upload interface.

If the user needs to insert the gallery manually, the workflow is slightly more complicated.

  1. Place the cursor precisely where the gallery needs to be inserted.
  2. Click the “Upload/Insert” button.
  3. Upload your attachments.
  4. If the order isn’t correct, change it by drag and drop.
  5. Click “Insert gallery” and don’t mess with the settings.

As we see, the second workflow isn’t that different, but there are two potential caveats where end users can mess up the gallery display. Therefore, the “automated gallery” method is more bullet-proof — the only thing that can go wrong is the order of the images (or having forbidden characters in the filename).

Enter the custom galleries!

I have been talking so far about the “default gallery”, and until now, that was the only gallery available in WordPress. It has some big limitations: you cannot exclude images from the gallery, or add other images from the Media Library. The only workaround would be to insert single images one-by-one into your post.

That’s certainly the biggest improvement in the new media uploader: it allows you to create custom galleries, by freely selecting groups of images, either images attached to the post, or from the Media Library. It’s a huge benefit for long-form writing, since it allows you to place small groups of images across your post. Hey, it would be extremely practical for this report I’m currently writing :-)

However, that shift of focus towards the custom gallery has taken away some possibilities from the default gallery.

In the current state of the new uploader, there is no way to see what images are attached to the post. We always see the entire media library, in chronological order. There is no visual distinction between images that are attached, and images that aren’t. That can be confusing when you are editing an older post. (Update, November 29: it’s now possible to display the attached media, but it needs a separate action).

An example: the user uploads 10 images to some post, and adds 5 of them to a custom gallery, keeping the 5 other for adding them at a later moment. When he resumes editing the post a few weeks later, he has a hard time finding the 5 attached images, since they are mixed with everything else that was added to the media library in the meantime.

Feature request #1: it should be possible to get a “default gallery” view, showing only the attached images (Update, Nov 29: this is now possible). That default gallery view should also allow re-ordering (see the next section). Update: see Trac ticket #22607.

Ordering images

One of the important things that the classic media manager handles quite well: re-ordering of items, either in a drag-and-drop manner, or by clicking “Sort Order: Ascending / Descending”.

Issues in the new uploader:

  • Re-ordering the default gallery is impossible, since there is no dedicated view of that gallery Update: it’s being fixed, see above.
  • Single-click re-ordering (“Sort Order: Ascending / Descending”) isn’t available. This may be related to the fact the the title isn’t visible in the new UI (since the Ascending/Descending ordering is based on the title).
  • Manually re-ordering a custom gallery with many images is difficult, because each preview measures 199px. On a 1440×800 screen, I can display 8 images. In the old uploader, with 32px icons, I can display 16 images.
  • It’s not always possible to guess the correct order by looking at the captions — sometimes, you need to see the title of the files. As mentioned previously, the title isn’t visible in the new UI (Update: it’s now visible when selecting an image).
Re-ordering images in the new vs. the old uploader.

Feature request #2: Allow single-click reordering for all galleries. Allow us to display the title when needed (fixed). Allow us to set a smaller preview size when working with large galleries.

Titles, Captions, Descriptions

Another important thing, when inserting images into a post, is the ability to add titles and captions. WordPress offers even more options, since it gives us the following fields: Title, Description (redubbed “Attachment Page Content” in the 3.5 media library), Caption and Alternative Text.

In terms of UI, this might be a bit overwhelming for a non-technical user. Probably that’s the reasoning behind the simplification in the new UI, where only the caption field is visible (with a “Describe this image” placeholder text) Update: Title and Alt fields have returned.

Editing image metadata in the uploader.

All fields can still be edited in the Media Library (with a new formatting toolbar for the description field), and I assume that they will be accessible from the Media Uploader at a later point. But let’s be explicit:

Feature request #3: Allow us to display the file metadata we need (title, description, alt-text) and give us an interface to edit it. Even better: let us define what fields we want to see (site-wide), and let us rename them (via functions.php).

What works, what doesn’t: overview

Here is an overview of the actions that are possible in the old and (currently) the new UI.

Basic actions Old New
Upload images and files Yes Yes
Access Media Library Yes Yes
See all attached files Yes Yes
See number of attached files Yes No
Insert all attached images with one click Yes No
Re-order all attached images with one click Yes No
Set featured image from uploader Yes No
Delete image from uploader Yes Yes
Insert single images
Set alignment (left, right…) Yes Yes
Set Link To (page, file…) Yes Yes
Set size (thumb, medium…) Yes Yes
Custom galleries
Create a gallery that excludes some attached images No Yes
Create gallery that mixes attached images with files from library No Yes
Create several galleries spread across the same post No Yes
Create a custom gallery and re-use it in another post No No
Titles and captions
Change title Yes Yes
Add/change caption Yes Yes
Add/change description Yes No
Add/change Alt Text Yes Yes

Keep in mind that development is very active, things are moving daily — therefore this overview is not necessarily accurate (latest update: November 29, 3.5-RC1-22913)

Here is the Trac ticket where the actual work is happening:

Update (31 oct, 19:56 UTC):
@koop writes:
A good amount of this is coming soon. It’s worth noting that the concept of “attached files” is being de-emphasized in 3.5.
Title and description are used only on attachment pages, so those fields are pushed to the edit attachment pages…
…with the exception of titles for non-image media. Alt text will be editable in the modal.

14 thoughts on “Notes on the WordPress 3.5 Media Uploader

  1. A very good post above and proved helpful to explain to the designer I’m working with some of the issues we might face with the upcoming release of wordpress 3.5.

    We are just about to explore building a wordpress based cms for an almost entirely image based (photography) website, consisting of galleries for a number of different photographers.

    WordPress seemed like a good and natural choice over their current cms, precisely because of the way images are ‘attached’ to posts and the what you refer to as the ‘default gallery’ is managed.

    In our case the posts would be a custom ‘photographer’ post. This would allow easy management of each photographers gallery from the ‘photographer’ post editing page.

    We were also planning to tag each image in each photographers gallery to allow work to be further sub-categorised (using one of the media tagging plugins that this media management update I’m guessing may break).

    This combined with custom taxonomies would have opened up all sorts of useful possibilities in developing our front end code, retrieving and filtering images, while still keeping the administration very easy for the user using built in core features.

    Unfortuantely it seems this new media window is going to make that more difficult for us and less user friendly for the user.

    The ‘create new gallery’ feature doesn’t really help at all in our case, as the gallery would not be inserted into the content area by the user, but instead be generated automatically by our template code (this is important for ease of use for our end client and allows us to do more useful things in the front end than simply display a simple gallery the user inserts manually on a particular page – which isn’t a suitable approach for many custom themes/developments).

    I could understand removing the reliance or emphasis upon image ‘attachments’ if there were alternative ways of categorising images (and managing them based upon category) in the media library as part of the core admin functionality, but there currently isn’t from what I can tell from reading about these new features and the screenshots available.

    As it is, it appears that when the user faces the task of managing the images for a particular ‘photographer’ in version 3.5, rather than have access to the usual ‘default gallery’ screen where they can manage images for that particular ‘photographer’ post, they will instead be presented with images from ‘all photographers’, making their life much more difficult.

    I will be playing around with wordpress 3.5 this evening to be sure, but if this is the direction things are moving in with wordpress, its looking like we may be forced to continue with their current cms (which although suffers by comparison to the current version of wordpress at least includes the facility to organise images and files into some form of category and manage them by category as part of its core functionality).

  2. @JB: indeed, it looks like we are facing the same issues with the new uploader.

    Since the iron is still hot and flexible, now is the best moment to take action and help the dev team in shaping this tool.

    Apart from writing code, here are some ways of getting your voice heard:
    – write a blog post that explains your workflow, and how the uploader should work to help the user.
    – create graphic mockups showing how the “perfect” uploader should look like, and post them on trac.
    – take part in the tuesday evening UI team chat.

  3. @manu – thanks for responding :)

    I noticed that in this ticket below the developer of the new functionality suggests that the attachment relationship will still be present which gives me a little hope (that even if they don’t include a way of managing attachment images like the old ‘gallery’ tab, we can at least build something ourselves or find a plugin at some point when wp 3.5 is released to restore the old functionality when we are ready to upgrade sites that rely on that workflow):

    I’ve installed the 3.5 beta this afternoon to look at it more closely, and as a way of building galleries that you insert into a page/posts content area I must admit I quite like it. Its a definite improvement in this respect. But that’s all it is to my eyes in its current form – a way of building a gallery tag featuring any image from the library and not suitable as a complete replacement for the functionality that we already had.

    I appreciate your suggestions, and will look into contributing when I have a bit more time, though I think your suggestions here (and in the thread at: ) pretty well cover my concerns so far though.

    My ideal interface for this would be pretty much what we already had to be honest, perhaps with this new media manager available as a new window or a replacement for the old ‘media’ tab.

    Its not so much the uploader that I have an issue with (that works nicely in the new version too). Its more the lack of features for organising post attachments from the post screen itself. This is a significant limitation.

    In the beta I see the old upload/insert media button is still available, and if that will be the case in the final release that would be great. But I fear that when 3.5 is released that button is going to disappear and all we will be left with is a somewhat dumbed down and convoluted way of managing post attachments.

    This new approach to working would not be such an issue if there were also better ways of organising files into folders or categories, but in the absence of this, the new approach (if it is to replace the current system entirely) is going to be quite limiting when developing templates for wordpress for clients to use it as a cms (as opposed to a simple blog). This is a real shame because the custom post types and taxonomy features in recent versions of wordpress have made it more and more useful as a full blown cms rather than simple blogging platform.

    I can only hope that the developers of this new feature take your suggestions here seriously and reconsider the usefulness of being able to manage attachments on the post editor page for people using wordpress for something a bit more than a simple blog style workflow.

    We are at this stage forced with a tough choice of going ahead with wordpress (which we love and had planned to use) for the projects we have organised, or to start looking at alternative platforms that provide better image management/organisaation (this has always been a bit of a limit with wordpress imho but the way post attachments worked allowed custom theme developers to work around it – but it seems the remedy being suggested for that is only going to make things even more limited in this respect for anyone who wants to deal with images outside simple gallery insertions in the content area of blog style posts).

  4. ** I meant to say ‘faced with a tough choice”. Apologies for any typos/gramatical errors in my previous two posts. I was in a bit of a rush and should have taken the time to properly read my response before hitting submit.

  5. After having a bit more time to experiment with the new beta of wordpress 3.5 and check over some of the code, I notice it does actually now have support for attachment taxonomies in the core admin.

    From a few quick experiments this appears to work well. This is excellent and will prove very useful in the future, being able to define your own taxonomies for attachments very quickly in a few lines of code in functions.php in custom templates, just like you can for other post types.

    I’m still a bit disappointed by the de-emphasis of media>post attachment and the simplification of the interface when uploading files (specifically moving the fields alt-text, title and description away from the upload window where it is most convenient for the user to set them at the point the image is uploaded – and now expecting them to navigate to a different section to set these fields as per the current beta). But no doubt a plugin will emerge to bridge that gap for those that need it. Or if not we can look at building our own for the new release when the time comes and we need it.

    It strikes me that with attachment taxonomy support now part of the core admin functionality, it should be relatively easy to include a ‘save gallery’ button in the new media window (perhaps in addition to the current ‘insert gallery’ button that generates the simple gallery shortcode tag). This would allow galleries to be saved for future reference and re-opened across different posts very easily. At the point the first gallery is named and saved a ‘gallery’ attachment taxonomy could be created automatically (it would then become managable from the seperate media library area too – the functionality for that appears to be present already in the background now). By allowing that new gallery taxonomy id to be associated with posts (a simple post meta record could record that relationship transparently in the background) it would then be possible to associate a single gallery with multiple posts and be very helpful in custom template development (as it doesn’t rely so much on a shortcode that the user inserts manually into the page content area). The user interface for this could be very simple – just a list of all saved galleries with a checkbox next to them to associate them with the post. It could also allow for some interesting possibilities for interacting with the ‘insert gallery’ button – for example allowing a saved gallery to be retrieved, then selecting a subset of images from it to use the ‘insert gallery’ button to insert into the post content area as a shortcode tag. It may be a relatively small step for the wordpress developers to provide that sort of functionality or a plugin developer later I’m guessing.

    Regarding the management of post attachments I noticed in the latest build that the media window now includes a column to the left with ‘upload files’, ‘media library’ and ’embed from url’ links. By simply remaming that ‘upload files’ link to ‘uploaded files’ and showing all images uploaded to a particular post (rather than it forget once you navigate away from a post and go back again as it does currently), and allowing that file list to be dragged to sort, this would address the need for users with custom themes who need that workflow, without significantly changing or complicating the existing beta interface, while also slightly de-emphasising the attachment>post relationship like they want I think? It seems to me like it would be intuitive enough to the user and would make things a LOT easier for them to find and manage files that they have uploaded to a particular post in the past then want to edit again later, rather than have to dig through perhaps thousands of files in the whole media library to find them at a later date.

    Apologies for taking over your blog slightly with my lengthy comments here. I don’t really have much time to join the appropriate groups at the moment to make these suggestions directly to the developers (it doesn’t seem a simple matter of posting a comment but being introduced or registering and proving your worth before being accepted). My hope is that someone will read my comments here and consider making these suggestions to the core developers or that one of them will read them here and find some use in them (particularly the last suggestion as that will save a lot of wordpress custom theme users and developers from the ‘Oh crap what happened to the gallery tab and ordering’ moment that will be coming to them soon with the new release if they don’t check the changelog first before upgrading).

  6. I’m impressed with the overall features and functionality of the media uploader. Its great.

    I am however struggling to find a method to restrict or code-out the full presentation of all images in the popup. An admin control to limit the dropdown options or a singular restriction based on parent post attachment would be helpful.

    Any guidance that could be provided on where or how i might source a solution on this would be apprecaited. (Ive gone through WP forums, web search, meet up 3.5 video etc)
    In 3.4 I was able to initiate a function.php code to limit acess to the full library based on user. For multi-user sites i believe there will be a demand for restricted image presentation.

  7. As an update to my previous post I think Ive found a solution to my issue with a role scoping plugin. : )

  8. I have a photographic website with hundreds of photos that I had paintakingly added captions to. With the new wordpress release and its new image handling system, ALL OF MY CAPTIONS ARE NOW GONE! I can’t express how incredibly pissed I am over this. I checked various images in my library (I have over 80 pages of images in the library) and all of them have had the captions stripped out. They are just no longer there! It’s a good thing a WP developer is not within arm’s length of me right now otherwise I’d strangle them! And I’m normally a very peaceful gal!

Comments are closed.