Meta box controls – image and gallery upload controls

Custom metabox image and gallery upload

In this tutorial we'll cover the image upload, and gallery upload meta box controls. They are pretty useful controls, especially if you want to create a plugin that requires them.

In the previous article, we went through adding the slider and date picker controls. This time I’ll show you how to add image upload and gallery upload controls. For this we’ll use the built in handler. To be honest this was supposed to be covered last time (at least according ot my own to-do paper), but there was a request for slider control, so I decided to cover that first. We’ll continue in the same file as before, basically adding to the existing controls.

PHP part

Inside our mytheme_metabox_controls( $post ) function, we’ll add two variables that will check the meta data of the post for the image and galleries.

While you may think that we are essentially doing the same thing (gallery is just a bunch of images sorted together), the difference is quite big. In the case of the ‘featured image’ we’re storing the image URL, while in the case of the galleries we’ll store the attachment ID’s, so the way we display them and use them is quite different.

Inside our .right_part div, we’ll add

Also, for a better appearance, we’ll add the styles

in our inline styles at the top of the custom fields. We want to limit the size of the image container, since you can place a 2000px wide image, and you don’t want to display a 2000px wide image inside the meta box (that would just break the layout and overflow to the page). Also notice that in our code, we added a check to see if the image is present, so that we show the image, only if it’s saved in our meta data. No need to display an empty HTML.

This on its own won’t do much. We need to add some JavaScript to it. We’ve enqueued  admin.js file in the previous article to control the slider, and date picker. In the same file we can add

We need two functions – one to trigger the upload, and one for the removal of the image. Notice that we used  var custom_uploader = =; which is the call to the native WordPress media handle. Here we don’t want to allow multiple images upload, that’s why we added  multiple: false, and we are fetching the url of the selected attachment, and adding it to the input field, as well as attaching the <img /> element to the .uploaded_image element. On the remove button click, we just want to find the image, and the value in the input field and we want to remove those (empty them).

Saving the image

Now all we need to do is to save it. Inside the  mytheme_save_metaboxes( $post_id ) function, add

Gallery upload control

Next, we want to add the gallery upload control. This one is a bit different, although there are similarities with the image upload. First, we add the HTML and PHP part in like with the image control

Notice that we are converting our saved list of image IDs into an $img_array. That way we can control the output easier using the for each loop. The last part is almost the same as the image input, but the input field for the image IDs is hidden, since it’s just a list of numbers. To save it we’ll add in our save function that gets called on the save_post action

The important part here is the JavaScript. In our admin.js add

Now there is a small issue with my syntax highlighter and WordPress automatically detecting the shortcodes in the code above so in the line where it says

The code should  contain just one bracket on each side not two. So just be sure to change this small issue (don’t just copy paste the code :D ).

Notice the addition of the

code. This is a gem I found on StackOverflow that will prevent any double click issues that happened when you’d click on the ‘Manage gallery’ button. This time we need to call the and not just the frames (single image). The code is a bit longer, but you are basically manipulating the gallery shortcode to show your images. The rest of the code just places images in the .gallery_images element, and the IDs in the hidden input field, so that we can save them. There is also empty gallery code, which just removes everything from the input field and the images element, and the single remove function that will just remove the single image one at the time.

There is also the helper function that is used to remove item from an array by its value (we need it to remove single image from the gallery and the input field).

After this the gallery should work when clicked on the ‘Manage Gallery’ button.

The neat thing about the built in WordPress gallery is that you can add images to it, remove it, reorder the images in it and so on. On the meta box side I’ve added a little x on each image, so that you can remove individual image from the list. You’ll need to add some small inline css for it to be nicely styled:

The end result looks like this:

Image upload meta box without images

Image upload meta box with no images

Image upload meta box with images

Image upload meta box with images


It’s all nice to have the meta box controls, but how do we use them? For the single image just use the meta url in your page template:

For the gallery it’s a bit different. Since we have attachment IDs we need to fetch them first

And then use for each loop to get the image urls. Then you can even set the background as an inline style and use it as such

I hope you’ll find this tutorial interesting and useful. If you have any questions feel free to post them below, and as always, happy coding :)

Also published on Medium.

Join the Discussion

  • sonia maklouf

    Hi denis
    I was thinking about a tutorial about media library tutorial
    To be more precise when you edit a gallery. You have some select controls like columns, size, link to.
    It would be interesting to add an another select with masonry, grid etc option to shape the gallery.
    What do you think ?
    Would it be interesting or not ?

    • Great, I’ll add this to the list of to do articles. I actually did something similar for images in gallery (image post meta fields). Currently I have some personal projects I’m working on, but as soon as I find the time I’ll write a tutorial about this :)

      • michel lompret

        Hi Denis First I wanted to thank you for your precious and useful tutorial :-D they help me to understand a lot of things but there is one thing that stay obscure to me and it’s the page builder mechanism. I used page builder plugin for a long time . First visual composer and now elementor and I always ask myself how they get work. How visually edit a page and resize some module. I find it fascinating. I guess there’s lot to say about that but I think that if you do a series of tutorials about that it’ll have a great success because a lot of people use page builder without having any idea about how they work and I think there isn’t any tutorial explaining that :-)

        • Hi!

          Page builders are a different sort of beasts :D

          Especially visual based ones. You are basically loading everything in a separate container, and you need to keep track of every change. Different builders use different methods. Some use AJAX to communicate, some use ReactJS. It’s not a trivial thing to cover, and they are usually projects that take over a year to get in production (colleague on my job is working on such builder right now).

          Interesting topic, sure, but not trivial definitely :)

          • michel lompret

            ah I underestimated their complexity. This probably explain why there’s no tutorial about that