In this DiW article, you will learn some tasty ways to include image-attachment information in your posts. From echoing the latest image path to displaying custom-sized image-links for all post attachments, this article should serve as an invaluable resource for anyone working with WordPress’ Media Library and its media-attachment functionality.

Basic display of gallery attachments

When displaying your images via the [gallery] shortcode, WordPress will display image-links for each image in the gallery. Each of these image-links points to the image-gallery page for that particular image. The image gallery is created by the image.php template if present in your theme files. Here is a basic way to display your gallery images from within the image-gallery loop:

<a href="<?php echo wp_get_attachment_url($post->ID); ?>"><?php echo wp_get_attachment_image($post->ID, 'medium'); ?></a>

This code will display a medium-sized image-link to the original image. To display an image attachment of a different size, replace the $size parameter in the wp_get_attachment_image() template tag. Accepted values are thumbnail, medium, large, or full. The actual dimensions of these sizes are determined by your preferences in the Media panel of the WordPress Admin.

Display the URL of the latest image attachment

Perhaps the most useful template tag for displaying image-attachment information is wp_get_attachment_url(). This function returns a full URI for an attachment file. If no attachment is found, a value of false is returned. Here are several ways to use this tag within the loop:

<?php // display the attachment URI for post with specified ID
echo wp_get_attachment_url(7); ?>

<?php // display the latest attachment URI for each post from within the image.php loop
echo wp_get_attachment_url($post->ID); ?>

<?php // display the latest attachment URI for each post from within the index.php loop
echo wp_get_attachment_url($attachment_id); ?>

The output of this tag is similar to the following for each attachment:

http://digwp.com/wp-content/uploads/2009/08/example.png

If you are using the image.php file to display your attachments, use the second recipe to display the latest URI for each post. If you are displaying your attachments from any other template file (e.g., index.php, single.php, etc.), use the third recipe and refer to this section of the article for the code required to generate dynamically the $attachment_id variable for the post ID.

Display the latest image attachment as an image

The wp_get_attachment_image() template tag is used to display the latest image attachment as an actual HTML image element. If no image attachment is found, a value of false is returned. Here are several ways to use this tag within the loop:

<?php // display medium-sized attached image for post with specified ID
echo wp_get_attachment_image(7, 'medium'); ?>

<?php // display the latest attached image for each post from within the image.php loop
echo wp_get_attachment_image($post->ID); ?>

<?php // display the latest attached image for each post from within the index.php loop
echo wp_get_attachment_image($attachment_id); ?>

The output of this tag is similar to the following for each attachment:

<img src="http://digwp.com/wp-content/uploads/2009/08/example.png" class="attachment-thumbnail" height="50" width="50">

The wp_get_attachment_image() template tag may be customized with the following parameters:

<?php wp_get_attachment_image($attachment_id, $size='thumbnail', $icon=false); ?>

• $attachment_id — ID of the desired attachment. Not required if used within an attachment loop, otherwise, refer to this section to generate the ID for non-attachment loops.
• $size — Size of the image shown for an image attachment: thumbnail, medium, large or full
• $icon — (Optional) Use a media icon to represent the attachment. Default value: false.

Display the thumbnail of the latest image attachment

I couldn’t find any official documentation for the get_attachment_icon() template tag, but after some experimentation, it seems useful for displaying a thumbnail of the latest image attachment for each post. Here are some examples:

<?php // display image thumbnail for post with specified ID
echo get_attachment_icon(7); ?>

<?php // display image thumbnail for each post from within the image.php loop
echo get_attachment_icon($post->ID); ?>

<?php // display image thumbnail for each post from within the index.php loop
echo get_attachment_icon($attachment_id); ?>

The output of this tag is similar to the following for each attachment:

<img src="http://digwp.com/wp-content/uploads/2009/08/example.png" title="example" alt="example">

If using this tag within an attachment loop, such as in the image.php or attachment.php theme file, the post ID parameter is generated automatically. If using within a non-attachment loop, such as in the index.php or single.php theme file, refer to this section for the code required to generate dynamically the post-ID variable.

Other useful template tags for displaying image attachments

Here are some other useful template tags for displaying image attachments and their related information:

<?php // returns the URL for the latest attachment thumbnail
wp_get_attachment_thumb_url($attachment_id); ?>

<?php // returns an image representing the latest attachment file
wp_get_attachment_image_src($attachment_id, $size='thumbnail', $icon=false); ?>

<?php // returns an image-link or text-link to the latest attachment file or attachment page
wp_get_attachment_link($id=0, $size='thumbnail', $permalink=false, $icon=false); 

<?php // displays an image link to the latest attachment file
the_attachment_link($attachment_id); ?>

<?php // returns an image link to the latest attachment file
get_the_attachment_link($attachment_id);  ?>

<?php // returns a URI to the attachment page for the latest attachment
get_attachment_link($attachment_id);  ?>

See the next section for generating the values of the $attachment_id variable.

Dynamic generation of the post ID for non-attachment loops

If you are using any of the above recipes within a single.php, index.php, or any other non-attachment loop, you will need to include the following line of code to generate the ID for each post:

<?php global $wpdb; $attachment_id = $wpdb->get_var("SELECT ID FROM $wpdb->posts WHERE post_parent = '$post->ID' 
AND post_status = 'inherit' AND post_type='attachment' ORDER BY post_date DESC LIMIT 1"); ?>

This code dynamically generates the $attachment_id variable that is used in some of the examples above. Here is an example showing how to display the latest attachment URI for each post from within the index.php loop:

<?php global $wpdb; $attachment_id = $wpdb->get_var("SELECT ID FROM $wpdb->posts WHERE post_parent = '$post->ID' 
AND post_status = 'inherit' AND post_type='attachment' ORDER BY post_date DESC LIMIT 1"); 
echo wp_get_attachment_url($attachment_id); ?>

Enough of the simple stuff! Let’s move on to some more advanced recipes.

Display all attachments for each post

Up to this point, we have been using template tags to display information related to the latest attachment only. With any of the above methods, the output for any of the template tags represents a single attachment item. In order to display multiple attachments for each post, we need to employ WordPress’ get_children() functionality. The get_children() tag returns an associative array of posts with post IDs as array keys. The default parameters are as follows (as of version 2.7):

$defaults = array( 
	'post_parent' => 0,     // get children of this post ID; null value gets all children
	'post_type'   => 'any', // post type: attachment, page, revision, or any; default: any
	'numberposts' => -1,    // number of child posts to retrieve; default: -1 (unlimited)
	'post_status' => 'any', // post status: publish, draft, inherit, or any; default: any
);

For (cough) complete information (cough), refer to the official documentation.

Using this functionality, we are well-equipped to use any of the previously discussed template tags (or any other attachment-related tag) to display all of the attachments for each post in the loop. Here is the basic technique, using the wp_get_attachment_link() template tag:

<?php 
$args = array(
	'order'          => 'ASC',
	'post_type'      => 'attachment',
	'post_parent'    => $post->ID,
	'post_mime_type' => 'image',
	'post_status'    => null,
	'numberposts'    => -1,
);
$attachments = get_posts($args);
if ($attachments) {
	foreach ($attachments as $attachment) {
		echo apply_filters('the_title', $attachment->post_title);
		echo wp_get_attachment_link($attachment->ID, 'thumbnail', false, false);
	}
}
?>

When used within the loop, this code will output the title and thumbnail-size image-link for every attachment of each post within the loop. As is, the image-links point to the URI of the original, full-size attachment file. To get the image-links to point to the attachment page for each image, change the third parameter in the wp_get_attachment_link() tag to true.

Currently, the function will display all attachments for each post. To limit the number of attachments displayed, change the numberposts value from “-1” to whatever number you wish.

Once you get the hang of this basic attachment-display method, you can have some fun experimenting with different output formats by swapping out and/or including additional template tags. For example, instead of displaying a thumbnail link along with the attachment title, you may want to display the URI of the original attachment. To do so, you would simply replace this line:

echo wp_get_attachment_link($attachment->ID, 'thumbnail', false, false);

..with this:

wp_get_attachment_url($attachment->ID)

Now, what about all of the other tags? How to implement and integrate them into a cohesive configuration of image-attachment bliss? There are far too many possible configurations to even begin to cover them all, but I did come up with an effective way of demonstrating the configurational possibilities with a little function I like to call the “Attachment Toolbox”.

Image-attachment enlightenment with the Attachment Toolbox

The idea is simple: learn by example. This function is essentially a “live” demonstration of the various template tags and their generated output. To use this function, create a few posts and attach some images (or other types of attachments) to each of them. Then, place the following code into your theme’s functions.php file:

<?php 
function attachment_toolbox($size = thumbnail) {

	if($images = get_children(array(
		'post_parent'    => get_the_ID(),
		'post_type'      => 'attachment',
		'numberposts'    => -1, // show all
		'post_status'    => null,
		'post_mime_type' => 'image',
	))) {
		foreach($images as $image) {
			$attimg   = wp_get_attachment_image($image->ID,$size);
			$atturl   = wp_get_attachment_url($image->ID);
			$attlink  = get_attachment_link($image->ID);
			$postlink = get_permalink($image->post_parent);
			$atttitle = apply_filters('the_title',$image->post_title);

			echo '<p><strong>wp_get_attachment_image()</strong><br />'.$attimg.'</p>';
			echo '<p><strong>wp_get_attachment_url()</strong><br />'.$atturl.'</p>';
			echo '<p><strong>get_attachment_link()</strong><br />'.$attlink.'</p>';
			echo '<p><strong>get_permalink()</strong><br />'.$postlink.'</p>';
			echo '<p><strong>Title of attachment</strong><br />'.$atttitle.'</p>';
			echo '<p><strong>Image link to attachment page</strong><br /><a href="'.$attlink.'">'.$attimg.'</a></p>';
			echo '<p><strong>Image link to attachment post</strong><br /><a href="'.$postlink.'">'.$attimg.'</a></p>';
			echo '<p><strong>Image link to attachment file</strong><br /><a href="'.$atturl.'">'.$attimg.'</a></p>';
		}
	}
}
?>

Then, in your index.php or single.php (or other non-attachment) loop, call the function with the following tag:

<?php attachment_toolbox('thumbnail'); ?>

Then check the results in your browser. You will see that the code has output a variety of different attachment data, including title, attachment URI, post URI, image URI, image thumbnail, image links, and so on. After examining the output, refer back to the function itself to understand the functionality of each tag. Once you begin to see the correlation between source code and page output, you will be well equipped to transform the function in any way you see fit, or even use it as a guide to create your own custom attachment-display function. It’s all there, just dig in and check it out :)

Check please

That does it for this fun-filled DiW article. We have seen how to display many different types of image-attachment information, including everything from thumbnail links and URL paths to custom-sized images and multiple attachments. This collection of recipes is by no means exhaustive, but it provides plenty of key techniques to help implement and customize your own image-attachment functionality. Working with WordPress’ Media Library can be a convoluted process, to say the least, so any tips and tricks that you happen to know will be greatly appreciated by the incredibly awesome WordPress community.

© 2009 Digging into WordPress | Permalink | 46 comments | Add to del.icio.us | Post tags: attachments, images, tags, tips, tricks