Theme Development

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.

	Template Name: Gallery Page

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.


	$args = array(
		'numberposts' => -1, // Using -1 loads all posts
		'orderby' => 'menu_order', // This ensures images are in the order set in the page media manager
		'order'=> 'ASC',
		'post_mime_type' => 'image', // Make sure it doesn't pull other resources, like videos
		'post_parent' => $post->ID, // Important part - ensures the associated images are loaded
		'post_status' => null,
		'post_type' => 'attachment'

	$images = get_children( $args );
	// continued below ...

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.

	// continued from above ...
	if($images){ ?>
	<div id="slider">
		<?php foreach($images as $image){ ?>
		<img src="<?php echo $image->guid; ?>" alt="<?php echo $image->post_title; ?>" title="<?php echo $image->post_title; ?>" />
		<?php	} ?>
  	<?php } ?>

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.

	<script src=""></script>
	<script src="<?php bloginfo('template_url');?>/js/flux.min.js"></script>
		window._flux = new flux.slider('#slider',{pagination: true});

	<?php wp_footer(); ?>

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!

Related Posts
  • Code
    Creative Coding
    Advanced Use of Attachments in WordPress: Creating Custom Queries for AttachmentsAdvanced use of attachments in wordpress 400
    This tutorial is the second in a four part series in which you'll learn some techniques for working with images in attachments in WordPress which give you advanced options.Read More…
  • Code
    Creative Coding
    Advanced Use of Attachments in WordPress: Assigning Categories and Taxonomy Terms to AttachmentsAdvanced use of attachments in wordpress 400
    This tutorial is the first in a four part series in which you'll learn some techniques for working with images in attachments in WordPress which give you advanced options. Read More…
  • Code
    Creative Coding
    Using a Custom Post Type to Create a Home Page BannerUsing a custom post type to create a home page banner
    Sometimes it's useful to have a nice obvious banner on your site's home page—for announcements, snippets that aren't long enough to merit a blog post, or links to new content within the site. But you don't want to be editing your homepage content every time you add a new piece of content, nor do you want to be delving into the code to add content.Read More…
  • Code
    Theme Development
    Creating a WordPress Theme from Static HTML: Creating an Archive TemplateCreating wordpress theme from html 400
    If you've been working your way through this series, you now have a functioning theme with two page templates. The steps I've demonstrated to this point are: preparing your markup for WordPress converting your HTML to PHP and splitting your file into template files editing the stylesheet and uploading your theme to WordPress adding a loop to your index file adding meta tags, the wp_head hook and the site title and description to your header file adding a navigation menu adding widget areas to the header and sidebar adding widget areas, a colophon and the wp_footer hook to the footer file creating template files for static pages. Read More…
  • Code
    Creative Coding
    Using WordPress for Web Application Development: Features: Custom Queries with WP_QueryApplication foundation 400
    We've been looking at how WordPress can be used as a foundation for application development, but one of the things that we've yet to cover that most modern frameworks offer is how to query the database to retrieve results for any given view. Specifically, we haven't talked about how to get information out of the database and insert it into our pages.Read More…
  • Code
    Theme Development
    How to Create a Homepage With Multiple Listings Using Custom QueriesFrontpage custom queries preview 400
    WordPress gives you a couple of built-in options for your website's front page: a display of your most recent blog posts or a static page of your choice. But what if you want to create something a bit more interesting than that? If your site has a lot of data using categories, taxonomies or custom post types to organize it, you might want to display data of more than one kind on your homepage. The good news is that you can do this using a custom template for the homepage. In this template you write a number of custom queries to list the data in the way you want to. In this tutorial you'll learn how to do the following: Create a custom homepage template for use by your theme Include four queries in that template to display different kinds of data, including three custom queries The queries will list standard posts plus one custom post type registered for this project, called 'animal'. You can find the template file with the four queries in the code bundle.Read More…