April 27, 2013

Creating a Filterable WordPress Photo Gallery Using Isotope


In a previous article we created a photo gallery custom post type in WordPress. I have had numerous requests to create a front end to tie it all together, so lets go!


A simple theme with some good logic can go a long way in the UI/UX department. The goal of this tutorial is to create a one page website that shows some photography that is filterable and viewable via a lightbox.

Note, that I will be using SASS in this project. Feel free to write the css anyway you please.

Add Another Custom Image Size

You should already have most of the code above from the previous tutorial. We need to add an additional size to create our front-end. On line 8 we add another size called album-grid that will be 450px by 450px. That was simple enough.


We need to create the default style.css to let WordPress know some information about the theme we are creating. I’ve copied the compiled SASS above, but feel free to remove the generate comments and to format the CSS above however you want.

Notice how on line 117, we do some crazy percentages. Let me explain why we did that. Browsers can usually support CSS percentages up to the fourth decimal place (ie – 33.3333%), but Javascript rounds off the fractional pixels, which can cause the last photo to sometimes drop to the next line when Isotope does the math which leaves a gap. So, we make the list item smaller to give Isotope plenty of room to fit it in where it belongs no matter the browser window width. We counter this by making the anchor link and image slightly bigger, thus making it look perfect.


Next, lets create the header.php file that we can apply to our template later. Notice, we are using HTML5, but you don’t have to. In our head we are calling some stylesheets, a Google font API and our wp_head.

In the header, we are including the logo and a options div that will display our custom tag cloud, if it exists, that we will build in just a bit.


The footer.php is simple.


The functions file is a little more complicated, so let’s break it up into a couple of different sections. I will run though it, so you can possibly copy and paste each section and it will work.

To be honest, I would really break this up into multiple files on a real project and include all of the different parts in a lib file within our theme and then branch them in to segments (inits, core, gallery, extensions, etc). Yet, for the sake of time, let’s put it all together with the code from the previous tutorial.

In this function, we are registering all of our javascript files the right way within wordpress. You could just include them in the header.php file, but WordPress has no idea of what you are doing. By enqueuing the files, we can set dependencies and place them in the header or the footer.

We are using Modernizr because we are using HTML5, so if you are not using it you can leave it out.

I am loading most of the scripts from a Content Delivery Network, so you can keep it that way or go download the files and make them local. I would suggest you keep using jQuery from the Google CDN because it reduces bandwidth usage, is minified and increases the chance that the user has already cached the file.

I know this looks like a ton of code, but it really isn’t. We are basically cloning the core WordPress wp_tag_cloud and wp_generate_tag_cloud functions so we can make some tweaks in how they are generated and displayed. We also allow the core tag cloud the ability to be used for the blog or any other part of the site.

The above function simply goes to our custom post type of gallery and grabs the phototype and displays it. We can use this inside the loop and will also keep our HTML cleaner.


In the jQuery above, the first thing we do is to activate noConflict mode. I always do this when working with WordPress because it keeps our javascript from conflicting with any javascript Worpress needs.

Next we run Fancybox and make sure it knows that we are using images (Fancybox absolutely throws a fit if it doesn’t have an explicit documentType with WordPress) and we also need the overlay helper to lock the background when Fancybox is initiated. I found that there was a weird spacing bug when dealing with Isotope. Remove the helper and see for yourself. You can read more about Fancybox and its API here.

Next we need to tell Isotope what we want it to do, because it can do a lot of cool things. On line 26, we set a container variable to save us some keystrokes. Line 28 is when we initiate Isotope and tell it want we want it to watch for (itemSelector), what layoutMode we want, which animationEngine to use (best-available checks to see if the CSS3 transitions can be used and if not fall back to jQuery) and finally how many columns we want.

Next we need to tell Isotope what we want to filter. On line 46, we tell Isotope to find the anchor links insite of the options div and add a click function on line 50 to actually initiate the filtering. You can see more examples of Isotope and how to use it here.


Finally! Let’s get down to writing the WordPress loop. First we get the header.php file we made earlier. Then we start our WP_Query and loop. Notice we do not query_posts! Query_posts should never be used and I see it used more and more on the intranet. Don’t do it! Okay, I’ll step off my soap box now.

Wrapping It Up

I’ve commented the code pretty well and tried to talk about the important steps in the process. Let me know if you have any questions or problems and I will do my best to solve them.

Be sure to include the Fancybox images in your theme.

Feel free to download the zip file that contains the whole WordPress Photo Gallery project to see the whole thing together. It also includes the SASS config and stylesheets, as well as the images.

Now, I am off to grab a smooth glass of Yamazaki whiskey.