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.