Your Own Instance of the WordPress Media Uploader

One of the nicest features of WordPress 3.5 was the introduction of a refresh of the WordPress Media Uploader.

For developers who aren’t familiar with the change, the short of it is a new version of the media uploader was built using Backbone.js and Underscore.js both of which are newer JavaScript libraries that introduce a different type of structure to creating JavaScript-intense web applications.

Sometimes, one of the challenges that comes with working with any new feature is the lack of documentation around how to take advantage of it. When that happens, you’re more or less left to dig into the core source code and/or the documentation for each of the specific libraries to learn how to use them.

The WordPress Media Uploader

When working on the Pressware Image Widget, one of the things I knew I wanted to take advantage of was the new WordPress media uploader.

The WordPress Media Uploader

Not only did it provide an opportunity to learn how to work with some new libraries, but it also helped make sure the user was able to add an image using an interface that was consistent with the rest of WordPress.

To be clear, I wouldn’t say I have a solid understanding or even any significant experience with Backbone or Underscore – instead, I’d say I’ve learned how to use them within the context of WordPress and under a very specific implementation at that.

Anyway, creating your own implementation of the WordPress media uploader isn’t terribly difficult. The problem is, right now, there’s not a lot of information for how to do it, so I thought I’d share how I implemented it within the Image Widget.

At the very least, it provides code you can drop into a project for tinkering or for extending for a something of your own.

1. Define the JavaScript

Most of the time, I like to try to explain what the code is doing within the actual post, but, in this case, I’ve heavily commented the code. I did this primarily for my own benefit, but it saves some characters here in the post.

Just so you have some context to the code, here’s the general outline of what it’s doing:

  1. Define a handler to display the uploader when the DOM is ready. As the code says, you’ll actually want to change this in a production-level implementation.
  2. If an instance of the `file_frame`, which is a reference to our media uploader, has been defined, then we can go ahead and open it; otherwise, it needs to be created.
  3. Setup a handler such that when an image is selected, we dump the properties (that is, their key and value pairs) to the console.
  4. We open the the media uploader.

As mentioned, the code is heavily commented so it should be clear enough to follow.

2. Include the Scripts

Next, the JavaScript files need to be included in the WordPress Dashboard. If you’ve ever included your own JavaScript file, then this is business as usual:

This is what you’d place in a plugin or in a theme functions file. Obviously, I’ve opted for the latter as far as this example is concerned.

Other Implementations

This is a really really basic implementation of the WordPress media uploader. There are other implementations that already exist in core that allow you to insert galleries, insert multiple images, get more image details, and so on.

Clearly, that’s not covered here – perhaps another post – but hopefully this provides a stronger foundation off of which to work with the new media uploader.

7 Replies to “Your Own Instance of the WordPress Media Uploader”

  1. Hello, Tom!

    I’ve recently read your great Settings API Guide on Tuts+ and I’m happy that I found a tutorial of yours on how to implement the Media Uploader.

    I’ve already read several tutorials on how to do it and I’m bangin’ my head on the wall because I can’t make it work. But guess what? Your approach is beautifully working! But not quite as I needed it to…

    Well, my goal is to implement the Media Uploader on my Options Page (built with help of your articles on Tuts+), where I put some places to upload images. It’s currently working with plain file input fields, but as you might deduce, I want to provide a seamless and consistent experience through WP to my client.

    Yout tutorial in here was the very first thing that made the media uploader appear, but what I need is to fire it when one clicks on the “upload” button next to a text field which would store the selected image url.

    I’m desperate; nothing else works, and anyone in the WP forums answers me and I don’t understand jQuery!…. Could you please please please help me?

    Thanks in advance.

    1. Hey Yara,

      Unfortunately, covering something like this would require far more time than I have to dedicate to it in a comment. If the opportunity arises to cover it in a future post, I will!

      I wish I could be more help, but all of the resources you’ve mentioned above are what I have on the topic.

      1. Thank you for answering, Tom.

        Actually, I’ve revisited some of the tutorials I saw before and made it work.

        Now I just need to find out how do I keep the URL in that text field when I save and refresh the page… If I’m not abusing, any tips? :)

        1. > Now I just need to find out how do I keep the URL in that text field when I save and refresh the page… If I’m not abusing, any tips? :)

          Sure! What you can do is pull the value out of the area in which it’s stored via something like `get_post_meta` or `get_options` and then place that value in the `value` attribute of the `input` element you’re using.

Leave a Reply