Students get a Tuts+ subscription for just $45! Hurry limited offer.

Creating Your Own Image Gallery Page Template in WordPress


Today I'm going to walk you through creating a custom template for "Gallery" pages in WordPress. I remember in the past wanting to implement a gallery into my theme and getting frustrated with the options. WordPress' built in gallery works well, but doesn't quite fit the bill most of the time. Additionally, plugins like NexGen gallery are often more than you need or want. I will show you how easy it is to create a gallery template page that you could easily tweak and modify for future themes or versions.


Through the tutorial I'm going to show you how to create a gallery template on the theme included with WordPress, TwentyEleven. You can use any theme you want but for this example's sake I'm using TwentyEleven.

Step 1 Duplicate the Existing Page Template

Go into the theme directory, wp-content/themes/{theme} that you want to add the gallery template to. Find page.php and copy and paste and rename to template-gallery.php. For custom templates I like adding the prefix 'template-' as it makes it easier to find.

Step 2 Define the Gallery Template

WordPress recognizes template definitions in the header of the themes template files. To define the template you add a PHP comment like the example below. To do that open the template-gallery.php that you just created and add the comment block what specifies the template name.

Step 3 Edit Template to Load Page Images

WordPress processes attachments to pages as posts post_type - attachment with the page as the parent. WordPress has a built in function to query posts that are children of a specific page post/post_type. get_children(); accepts all sorts of parameters for pulling children content associated to a parent. Check out documentation at This WordPress function allows us to easily pull attachments for a specific page.

For our gallery, we want the images to appear before the content. So we are going to load the page images in the page loop but before the content. For TwentyEleven you can place the snippet right below <?php the_post(); ?>. In other themes you can insert the code in the loop above <?php the_title(); ?>. Check out the code below to see how get_children( $args ); is implemented and read the explanation after it.

Explanation of $args

  1. 'numberposts' We can define the amount of images the function pulls. To query all images, use -1
  2. 'orderby' We could order by title or date or another option, but the benefit of 'menu_order' is that the order in the media manager for the page will be the order the images are loaded.
  3. 'post_mime_type' We only want the posts that are 'images'
  4. 'post_parent' We want to pull the children of the current page. We can access the global $post and it's property ID to pass in as the parent_id
  5. 'post_type' 'post_mime_type' takes care of making sure only images are pulled, but defining the 'post_type' as 'attachment' helps slim down the query.

Verify the post has images and loop

After get_children( $args ); queries up attachments and returns values we want to verify that the query returned results. Some pages may not have images attached and we don't need to loop through empty results. We'll use a conditional to see if $images returns a value, and if it does, then we know the page has attachments and then we can loop through them.

For each image attachment we want to output the image. Each $image object has several properties you can access and output. The most important for this example is the source of the each image, which is the guid property. For accesibility and SEO purposes we can ouput the image title and place in the image alt & title attributes of the images.

Step 4 Add the Javascript Gallery Plugin

For the next step we are going to add a jQuery plugin to bring our gallery to life. The plugin we are going to use is Flux Slider, a slider Javascript/jQuery plugin. Download the source and place the flux.min.js inside the wp-content/themes/{theme}/js folder. Since I am using the TwentyEleven theme, jQuery is not included on the public side, so I will need to make sure to include it - if you are using a different theme, make sure jQuery is loaded.

Edit footer.php

Include jQuery (if not aleady included) and the flux.min.js script in the footer - make sure flux.min.js is below the jQuery inclusion but before wp_footer(); function.

The End

As you can see, it's pretty easy to pull images attached to a page and customize their output. You could easily include this same loop in posts or a custom post type.

You could easily swap the jQuery plugin for another option of your choice. All you have to do is edit the loop HTML with the appropriate markup and include the plugin.

WordPress is very flexible, and this is another example of how easy it is to build with it!