Spring Sale! Save 30% on all books w/ code: PLANET24
Web Dev + WordPress + Security

WordPress Custom Fields, Part I: The Basics

[ Magnetic Fields ] 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:

Update: In the Admin Area, WordPress now refers to a custom field’s “Key” as its “Name”. So for custom fields, “key” and “name” refer to the same thing.
[ Screenshot: Pre-populated 'Key' field dropdown menu ]
Existing custom fields will be displayed in the dropdown menu

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:

[ Screenshot: 'post-icon' value entered in 'Key' field ]
If the custom key value does not yet exist, we can enter it manually

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:

[ Screenshot: Both 'Key' and 'Value' fields populated with data ]
With both "Key" and "Value" fields populated, 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 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 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.

So 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 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 way1 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 and display them anywhere in the theme template. So with that in mind, 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; ?>

Then after adding the secondary loop to our sidebar, we embellish it like so:

<?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

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

About the Author
Jeff Starr = Web Developer. Security Specialist. WordPress Buff.
BBQ Pro: The fastest firewall to protect your WordPress.

40 responses to “WordPress Custom Fields, Part I: The Basics”

  1. Kim Woodbridge 2009/01/14 9:16 am

    Oh Jeff – Thank you! While I sort of understood custom fields I now get it because of this tutorial. I really appreciate how you include details for every step. Many would have said “now put it in a loop in the sidebar” but instead you went through all of the steps. Ok – now I’m going to read Part 2

  2. Glad to be of service, Kim! Some people may prefer to forego the more detailed explanations, but many articles — especially the ones covering the basics of a topic– simply wouldn’t be complete without them. As always, thank you for the positive feedback — I hope you enjoy Part 2 as well.

  3. How do I use a conditional with this?

    Suppose I want to use this logic:

    If this post’s custom field with key “thumbnail” contains nothing, do not display it.
    However, if the field “thumbnail” contains a value, then display it.

    Thanks.

  4. @Bobo: Check out the follow-up post to this article. In it, you will find the exact method you describe, along with many others as well. :)

  5. This is an excellent written article. I have been trouble finding an easy and effective way to do this as I wanted the same image functionality like on most news websites. Just a quick note, for the sidebar image thumbnails, if I wanted the excerpt of the post to also appear, would it just be as straight forward as to include the php excerpt script?

  6. @Mike: Absolutely. Use the loop provided in the article and place any WordPress tag (including the_excerpt()) wherever you wish. Great question — Thank you!

  7. Thank you so much!

  8. This is actually the clearest lesson on how to output custom fields that I’ve found (the Codex is pretty vague on the whole “$post->ID, ‘post-icon’, true” thing). Thanks a lot.

  9. Jeff Starr 2009/03/02 9:13 am

    My pleasure, Michael — thanks for the positive feedback :)

  10. Great post Jeff, it has been really helpful.

    One issue I still have regarding custom fields is that when I implement it at the very end of the wp loop, my custom field values display below my plugins. I want i want my custom field values to display after my content and above my plugins. I am currently using wp 2.8 with the “addthis” plugin activated on all post. Any suggestions on how to fix this?

  11. Jeff Starr 2009/07/05 9:25 am

    @Tommy: You might try looking around in the plugin for the add_filter() function and set a lower priority for it. The filter should look something like this:

    add_filter('the_content', 'add_this');

    The default is “10”, so if there is nothing listed then you may want to try increasing it to a higher value (like “999”). Lower numbers correspond to earlier function execution.

    For more information, check out the Codex:

    http://codex.wordpress.org/Function_Reference/add_filter

  12. hey jeff, thanks for the suggestion. I’ve tried lower the priority of the functions, but because it executes within the ‘the_content’ loop it will always appear before the content in my custom fields. I haven’t found an easy way to implement contents from a custom fields in the ‘the_content’ loop, i have only been able to have it execute before or after “the_content”

Comments are closed for this post. Something to add? Let me know.
Welcome
Perishable Press is operated by Jeff Starr, a professional web developer and book author with two decades of experience. Here you will find posts about web development, WordPress, security, and more »
Blackhole Pro: Trap bad bots in a virtual black hole.
Thoughts
I live right next door to the absolute loudest car in town. And the owner loves to drive it.
8G Firewall now out of beta testing, ready for use on production sites.
It's all about that ad revenue baby.
Note to self: encrypting 500 GB of data on my iMac takes around 8 hours.
Getting back into things after a bit of a break. Currently 7° F outside. Chillz.
2024 is going to make 2020 look like a vacation. Prepare accordingly.
First snow of the year :)
Newsletter
Get news, updates, deals & tips via email.
Email kept private. Easy unsubscribe anytime.