WordPress Custom Fields, Part I: The Basics

I recently developed a theme that makes heavy use of WordPress’ custom fields. The custom-field functionality of WordPress makes it possible to rig up just about any customized layout quickly and easily. Custom fields enable designers to organize post content into different sections, making it possible to create non-linear page layouts, with different types of content easily removed from the normal post loop and relocated to different parts of the document. This organizational and design flexibility has the added benefit of making it super-easy to update your content, redesign your theme, and handle blog maintenance in general. In the first part of this mini-series, we walk through the process of implementing and using custom fields; then, in part two, I will share some delicious tips and tricks to help you get the most out of everything that custom fields have to offer.

Learning by example: Custom image gallery

To help us understand the process of implementing and using custom fields, let’s imagine a hypothetical design scenario wherein you would like to represent each of your posts with a unique thumbnail image. Specifically, in your sidebar, you would like to display the ten most-recent of these thumbnail images as links to their corresponding posts, thereby enabling users to browse the images and follow through to the full post at their convenience. While there are probably several ways to accomplish this configuration, we are going to take advantage of WordPress’ custom-field functionality to learn about custom fields while getting the job done.

Step 1: Add custom images to posts

The first thing we need to do is to add the custom images to our posts. So, let’s say we currently have three posts, and will be writing many more posts in the future. Open the first post in the admin edit screen and scroll down to the “Custom Fields” area. Each custom field requires two parts: a “key” and a “value”. For this tutorial, our key will be specifying different “post-icon” values, so let’s use “post-icon” as the name of the key. If the key has been used at least once before, it will be available in the “Custom Fields” drop-down menu like so:

The custom-field "key" will appear in the drop-down menu if it already has been used in another post

If the key is not listed in the drop-down menu (or if the drop-down menu fails to appear), we will need to add it by filling out the “Key” field. As this is the first post we are editing, we will create a key called “post-icon”, like so:

Since the custom key value does not yet exist, we add it to the "Key" field

Once the key has been specified in the appropriate field, we need to add its corresponding value. For this tutorial, we want each post to have its own custom thumbnail image, so we will use the image path as the value for this post’s “post-icon” key. Depending on the location of your custom images, your custom-field key/value pair should look like this:

With both "Key" and "Value" fields populated with the necessary data, we are all set

Click the “Add Custom Field” button to activate the custom field for the current post. Once done, this information is available to us in our WordPress theme files, thereby enabling us to call and display the custom post-images however necessary. Of course, the process we just went through should be repeated for all existing and future posts for which you would like to associate custom post-icon thumbnail images.

Step 2: Call and display the custom images

With the custom fields added to our posts, we are now ready to tap into some core WordPress functionality and display our custom post-images in the desired fashion. The function we will be using to retrieve the custom images is as follows:

<?php get_post_meta(); ?>

This is a native WordPress function designed to retrieve specific custom-field key values. The get_post_meta() function takes the following three parameters:

• $post_id — defines the post from which the custom-field data is called
• $key — defines the key of the desired custom-field meta value
• $single — specifies whether to return the data as a string or as an array

Plugged into the get_post_meta() function, these parameters look like this:

<?php get_post_meta($post_id, '$key', $single); ?>

To specify the ID parameter, $post_id, for each post, we use “$post->ID”, which requires the function to be placed within the loop. For the $key parameter, we will use the name of the target key, which in this case is “post-icon”. And finally, because we want the key value returned as a string, we use “true” for the $single parameter. At this point our get_post_meta() function looks like this:

<?php get_post_meta($post->ID, 'post-icon', true); ?>

And we are almost there. As is, this code will simply return the custom-field value without printing it to the web page. So, we make one final edit to echo the data to the browser:

<?php echo get_post_meta($post->ID, 'post-icon', true); ?>

When placed in the loop, this function will output each post’s “post-icon” custom-field value, which at this point is simply a URL to the specific thumbnail image. For example:

http://domain.tld/path/custom-01.png

Not very useful for your visitors, however, by enclosing our function with a little code, we can easily transform that URL into an actual image that links to its corresponding post:

<a href="<?php the_permalink() ?>" title="<?php the_title(); ?>">
	<img src="<?php echo get_post_meta($post->ID, 'post-icon', true); ?>" alt="Icon for Post #<?php the_ID(); ?>" />
</a>

That’s the ticket right there! Each post now includes its own custom icon that links directly to the single view of the post itself. In the next section, we will remove these custom images from their associated posts and display them in your sidebar as a consecutive thumbnail gallery.

Step 3: Display image gallery in teh sidebar

At this point, everything is setup, configured, and working great. We are successfully displaying custom post images that link to their associated posts. Now, to demonstrate the usefulness of WordPress custom fields, let’s remove our custom images from their respective posts and display them as a consecutive gallery within the sidebar. So instead of displaying this in the main column:

first post title
first post content
first custom image

second post title
second post content
second custom image

third post title
third post content
third custom image
.
.
.

..we have will display this in the sidebar:

first custom image

second custom image

third custom image
.
.
.

Without using custom fields, it is practically impossible to segregate intra-post data in this way. In other words, if we were to have included the custom-image URL along with the main post content, there would be no practical way ¹ of separating the information from the remainder of the post; they would always need to be displayed together. By placing the URL data within a custom field, however, we are able to display the custom data wherever and however we wish. In our current example, we are going to sequester the thumbnail images into the sidebar.

The catch here is that our get_post_meta() function requires the loop in order to work. Thus, to display our thumbnails in the sidebar, we will need to create a secondary loop within the sidebar itself. Fortunately, we have a number of tools at our disposal. For this tutorial, let’s go with everybody’s favorite loop function, query_posts. Without going into detail about the query_posts() function, suffice it to say that it is an excellent way to create multiple, customized loops just about anywhere in your design. Here is the basic structure of our second loop:

<?php query_posts(); ?>
<?php if (have_posts()) : while (have_posts()) : the_post(); ?>

// content goes here

<?php endwhile; endif; ?>

So, after placing that secondary loop into our sidebar, we embellish it as follows:

<?php query_posts('showposts=10&offset=0'); ?>
<?php if (have_posts()) : while (have_posts()) : the_post(); ?>
<a href="<?php the_permalink() ?>" title="<?php the_title(); ?>">
	<img src="<?php echo get_post_meta($post->ID, 'post-icon', true); ?>" alt="Icon for Post #<?php the_ID(); ?>" />
</a>
<?php endwhile; endif; ?>

As you can see, in the first line, we added two parameters — the first specifies the total number of loop cycles (ten, in our example), and the second indicates that we want the loop to begin with the most recent item (i.e., no offset). Beyond that bit of voodoo, we simply copy-&-pasted our previously marked-up get_post_meta() function into the “content goes here” portion of the loop.

Once we upload our newly edited sidebar.php file to the server, our web pages will feature the desired result: a nice thumbnail image gallery respectively linked to the ten most recent posts. Ahhhh.. feels so good! ;) Now let’s move on to some juicy custom-field tips and tricks! Actually, by the time I had finished this post, it was waayy too long (even by my standards) to publish as a single article. Thus, to alleviate the pain, I am breaking this post up into two parts. Stay tuned for Part II: Custom Field Tips and Tricks!

Footnotes

• ¹ I say “practical” because just about anything is possible with the right knowledge ;)