WordPress Theme Customizer – Custom Image Library

Recently while working for a client on the WordPress theme customizer, which I had never had an opportunity to used before, his requirements were that he be able to load images into the theme that are not part of the WordPress media library, as well as images that are part of the media library, as well as upload new images. Wow…complex task right? Below is what I came up with for him. He didn’t like the narrow image view that the uploaded images tab provided as his library of images will contain hundreds of images, and he also needed a way to categorize the images, oh, and he didn’t want to display the full size images for selection.

That probably isn’t clear…restated here are the requirements:

  • Be able to upload new images
  • Be able to select any images (and only images) from the media library
  • Be able to select images from custom locations
  • Have images in the custom locations be filtered by category
  • Display the images in the custom locations in a pop-up, rather than the standard narrow uploaded view
  • Be able to use the new selection for different parts of the theme customizer and be able to use different files for the different selectors

Awesome! Fun project! Read on to find out how I accomplished this for my client! Lets’ walk through the class step by step.

First thing was to extend the WP_Customize_Image_Control class to suit our own needs. Note that we only load this if the WP_Customize_Control class exists…otherwise we get big errors. We initialize some variables here too. Our class can be placed in your functions.php or some other file that is included in your theme in some fashion.

In the __construct we add a new tab to the display for our custom functions.

We modify the default tab_uploaded function to display any item from the media library that has a matching extension.

Our tab_library function brings in a custom thickbox css file, so it will display over the top of the customizer, and loads some other custom javascript we need to complete the process. Note, you may want to change the location of the files to suit your own needs, including maybe even changing the “get_stylesheet_directory_uri()” to “get_template_directory_uri()” depending on where you put things and your usage.

We set a link that is properly configured to open the thickbox window, as well as generate a random unique id so we can distinguish between multiple controls of the same type.

Finally, in the tab_library function, we have the code that will display in the thickbox window.

Let’s step through a few lines of that for fun. We get the options for our category select statement using a function we haven’t defined yet (ff_get_categories). If there is a problem retrieving options, rather than put in a broken SELECT tag, we will just put up an error message and an “Ok” button to close the pop-up. See how we have put in some special identifiers in the SELECT tag,  data-id and  data-fn? These will be used in the javascript we will discuss in a moment. Then we have our DIV that will hold the images once we get them. Lastly, our “Select” button that will pass along which image we selected to the customizer.

Our ff_get_categories function is pretty simple. It reads a file that should be a formatted CSV file and pulls category information out and places them into an series of SELECT OPTIONS. Nothing super fancy here.

And finally in our class we have our simple little function to generate a random string of characters. This could be fancier, but I think it suited our needs just fine. Don’t forget we are closing out the class and the if statement here as well.

Next we have a function that I would like to be able to include in the class, however since the WP_Customize_Control class doesn’t exist in AJAX calls, we can not include it in the class. This function will pull the image information and put it into OPTION tags passed back via AJAX. Again, nothing too special here. Maybe note that I didn’t include a nopriv action for this, because it can only be called from the customizer anyway, no sense in attempting to let a non-privileged user attempt to run it, huh?

Our custom javascript file (ff-image-picker.js) isn’t too huge. Has a jQuery statement to monitor when the category selection changes and then updates the images for that category by AJAX call. The other function is called when the “Select” button is pressed and it simply sets our setting with the image value selected. Information from the blog post WordPress Theme Customizer Javascript Interface helped immensely in overcoming one hurdle I had in applying the setting.

Two other files to mention, but not display here are for the jQuery Image Picker plugin used to display the images from a SELECT element. Recommend you get these files directly from the source on GitHub jQuery Image Picker.

To include the new setting in your WordPress Theme Customizer settings make sure you add your own section (if needed), control and setting. Samples of setting statement and control statement included for reference below. Note most of this is common to the standard WordPress Theme Customizer settings, but filename has been added for our class as a location to pull information about our files from a custom formatted CSV file. Each control can use it’s own CSV file.

The CSV file should be in the format of:  full size image path, thumbnail size image path, category, category, category, …, category with a nearly unlimited number of categories in the middle. Sample show here:

Note the extra comma at the end of the first line. This is because the file was generated by Excel and the second line has more columns. The code accounts for this already and works around it just fine.

A quick look at the final product:



You can download all of the files mentioned here, (without any setting or control information, sorry.) as a ZIP to do with what you want.

This entry was posted in Coding, JavaScript, jQuery, PHP, WordPress. Bookmark the permalink.

Comments are closed.