WordPress Settings API Media Uploader

I’ve built several settings pages on a few plugins, but I’m by no means an expert on the WordPress Settings API, and one of the things that remained difficult for me was creating an image upload that worked in conjunction with the the WordPress Media Uploader/Library, and saved the image to the database from a plugin’s settings page via the Settings API. I search the internet for quite a while, and I found countless tutorials and snippets, but none of them seemed to work exactly how it should.

Then I came across an article written on December 20, 2016 by Arthur Gareginyan, you can check it out here. This was the most recent article I could find on the subject matter, and it looked much less complicated that any of the other articles I had seen, so I decided to run with it. After initially following the instructions Arthur provided, it wasn’t quite working right for me, so I had to make some modifications, and I’m going to share those here. Keep in mind, this does not include instructions on setting up a plugin settings page, this code and information will assume you already that in working order.

There are a couple pieces to this. We’ll need a JavaScript file as well as a PHP file. You’re also going to need to invoke a built in WordPress function that will enqueue all scripts, styles, settings, and templates necessary to use all media JavaScript APIs in WordPress (Don’t worry, its easier than it sounds).

Let’s start with the JS as all you really need to do with it is enqueue it.

As a brief overview of the JS, what we’re doing here is hooking into built in JavaScript that we’ll enqueue with wp_enqueue_media(), which is the built in WordPress function mentioned above. Then we’re getting the image source URL and using it in our settings page. Again, easier than it sounds, and you really don’t need to worry about this, but I wanted to give you a short overview. There’s also a click function to remove the image in the settings page.

Take the following code, and paste it into a JS file that we’ll enqueue, or if you already have a JS file enqueued you can paste it in there.

Fore now, that’s it with the JS. Next, we’ll move on to the PHP. Create a PHP file that you’ll include in your main plugin file, or add the following code directly into your main plugin file. If you embed it directly in the file, make sure you remove the PHP tags in this snippet.

The next piece of code is our enqueue function. This will also go in your main plugin file. Because we only need this JS in the Admin area we’ll hook into admin_enqueue_scripts.  If you embedded the JS from above in an already existing JS file you can remove the wp_enqueue_script() line from this code. You may need to adjust the path in the script enqueue line as well so that it points to your new JS file.

As mentioned before, this assumes you already have a settings page that is formatted correctly using the Settings API. Now all you need to do is call the PHP function we added above inside your Settings Field callback function. So for example, you already have a settings field, and you have assigned the callback my_upload_callback() to it you would then do this to add your upload field:

The one thing to remember, when calling the arthur_image_uploader() you have to put the option name that you’re going to save to in it as seen above. That is a must, and this will not work without it. That’s it, my first blog post on the new site! Leave your comments below!

Leave a Reply

Your email address will not be published. Required fields are marked *