The built-in WordPress gallery systems leaves much to be desired. It works well if a theme supports it, but it can be difficult to customize, especially if you have any special markup you’d like with the gallery. While working on a client’s theme, I wrote up a quick short code function that can be used to display a gallery of all the attached images in any way that you like. The function is quite simple, and will be much easier to modify (especially in terms of markup) than the built-in gallery system.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
function pippin_gallery_shortcode( $atts, $content = null ) {
 
	extract( shortcode_atts( array(
      'size' => ''
      ), $atts ) );
 
	$image_size = 'medium';
	if($size =! '') { $image_size = $size; }
 
	$images = get_children(array(
		'post_parent' => get_the_ID(),
		'post_type' => 'attachment',
		'numberposts' => -1,
		'post_mime_type' => 'image',
		)
	);
 
	if($images) {
		$gallery = '<ul class="gallery clearfix">';
		foreach( $images as $image ) {
			$gallery .= '<li>';
				$gallery .= '<a href="' . wp_get_attachment_url($image->ID) . '" rel="shadowbox">';
					$gallery .= wp_get_attachment_image($image->ID, $image_size);
				$gallery .= '</a>';
			$gallery .= '</li>';
		}
		$gallery .= '</ul>';
 
		return $gallery;
	}
 
}
add_shortcode('photo_gallery', 'pippin_gallery_shortcode');

All this function does is get the ID of the current post, then check to see if it has any image attachments. If image attachments are present, then the images are looped through and displayed one at a time in an unordered list. Each image is linked to its own file with a rel=”shadowbox” for a lightbox effect (if you have the JS loaded).

The gallery can then be shown for a post or page by using the photo_gallery short code, like so:

[photo_gallery]

Since the function is just a simple loop, you can also customize the HTML markup exactly as you want.

  1. Bruce

    Excellent tip. Never thought of this… 🙂

    • Pippin

      Glad you like it!

  2. Blaine

    It’s worth noting that this will also display the featured image if present. If you’d like to exclude this, pass in the following argument:

    ‘exclude’ => get_post_thumbnail_id()

    I had an instance where a client wanted the ability to order the gallery manually. This can be achieved by utilizing WordPress’ built-in ‘Menu order’ option within the gallery’s settings. Just pass the following in as well.

    ‘orderby’ => ‘menu_order’

    • Pippin

      @Blaine – Thanks for the note. That is important to know.

  3. GreggFranklin

    Thanks Pippin, Just what I was looking for.

    • Pippin

      Excellent, glad to help.

  4. Claudio

    Great!! is there any chance to exclude always the first item in the gallery?? or hide it from the gallery grid and show it in another place in the page?? Thanks in advance.

    • Pippin

      Why would you want to exclude the first item? Are you thinking of something along the lines of excluding the featured image?

  5. Claudio

    What I’m trying to do is a portfolio page and upload a bunch o images hide the first image which will be a logo and then put it in another place in the portfolio page. Hope you understand.

    • Pippin

      I would personally set the logo as the Featured Image. If you can do that, then I can show you how to exclude that image.

  6. tommysvr

    Hi Pippin,

    Is there anyway you could give the first image a different class? I’m looking to use this in a slider and the first one needs a class of ‘active’.

    Also it doesn’t seem to like my sizing and always ends up making it a thumbnail:

    extract( shortcode_atts( array(
    'size' => ''
    ), $atts ) );

    $image_size = 'medium';
    if($size =! '') { $image_size = $size; }

    $images = get_children(array(
    'post_parent' => get_the_ID(),
    'post_type' => 'attachment',
    'numberposts' => -1,
    'post_mime_type' => 'image',
    'orderby' => 'menu_order',
    'exclude' => get_post_thumbnail_id()
    )
    );

    if($images) {
    $gallery = '';
    foreach( $images as $image ) {
    $gallery .= '';
    $gallery .= wp_get_attachment_image($image->ID, $image_size);
    $gallery .= '';
    }
    $gallery .= '';
    $gallery .= '';
    $gallery .= '';

    return $gallery;
    }

    • Pippin

      For adding a class to the foreach, you can do it like this:

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      
      $i = 0;
      foreach( $images as $image ) {
      	if($i == 0) {
      		$class = 'first-image-class';
      	} else {
      		$class= 'other-image-class';
      	}
      	$gallery .= '<li class="' . $class . '">';
      		$gallery .= wp_get_attachment_image($image->ID, $image_size);
      	$gallery .= '</li>';
      	$i++;
      }

      For the sizes, what size are you trying to use? Is it a custom size? If it is custom, then make sure you have regenerated the thumbnails.

  7. Peter

    Hello Pippin. I’d greatly appreciate it if you showed how to exclude the Featured image 🙂 Also, have any ideas on how to maybe change the order of the images in the gallery once they’re added? Thanks for your time man and for sharing the code

    • Peter

      Ok, so apparently I’m a dummy who should learn to read the whole thread before asking. I figured out how to do the exclude. How do I change the order though? Where and how do I modify this?

  8. Peter

    How do I order the gallery manually after passing the ‘orderby’ => ‘menu_order’ parameter? Please help a newbie out.

    • Peter

      Hello again Pippin. Thanks for taking the time to assist. I did not use the plugin you mentioned but managed to find another solution on my own and since it might help someone in the future I decided to share it here.

      The simple trick is that when editing a page use the Upload/insert button to bring up the Add Media dialogue. Then switch to the Gallery (x) tab which should be there. It lists all media attached to the given page. Then you can use the input fields on the right side to set index numbers for individual files. In my case I had to set them in a reverse order but it might have been my tinkering with your code that caused that. Anyways that’s it!

      Feel free to delete my multiple posts above to leave only what’s relevant. Take care man

    • Pippin

      Great!

  9. Anthony

    Thanx for sharing. How can you filter out images attached to the post through custom fields?

    • Pippin

      Can you elaborate?

  10. syelviani

    how to display all the image titles Attachments “title only” on Attachments page?

  11. Dan

    Pippin, I know this is an old post, but I have a question about using custom gallery shortcodes within the WP Editor.

    Is it possible to create a custom gallery shortcode but still use the visual gallery editor. I would like to create custom gallery options for my clients but I also want to let them use the visual Add Gallery functions within WP.

    Does this make sense? If so, how would that be possible?

    • Pippin

      I’m sure it is but I don’t know how you’d go about doing it, sorry.

    • Dan

      Thanks for the reply. I came up with a pretty good workaround where I have a modified gallery shortcode with a ‘types’ $atts that modifies the output based on type. I still have to go to the Text Editor to add the ‘types’ attribute to the shortcode but that’s not too hard to do. When I get a chance, I might work on a dropdown list for the ‘types’ attr within the Create Gallery window.

      Thanks for your contributions to the WP community.

  12. Dzung

    Thank you. This is what i’m looking for. But failed to operate. Does this work with custom post type and custom fields?

Comments are closed.