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. Book Author. Secretly Important.
Digging Into WordPress: Take your WordPress skills to the next level.

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

  1. Jeff Starr 2009/07/05 4:35 pm

    Hey Tommy, a few more things that come to mind:

    • Hard-code the plugin into the desired location in your theme file
    • Look into putting the_content in a variable and extracting the target contents via PHP
    • Use some CSS trickery to move the custom-field content above the plugin content
    • and, if all else fails, ..use JavaScript!
  2. thanks jeff. i’ll try ur suggestions this weekend.

  3. Hi,

    Just wanted to thank you for this outstanding tutorial. I spend a few hours banging my head against the wall trying to follow tutorials from other sites, including the official wordpress site, then I came across yours. It worked like a charm the very first time.

    Thank you, thank you and once again, thank you!

  4. Jeff Starr 2009/07/20 4:54 pm

    @Karl: You are most welcome! :)

  5. Great, It was useful to me in the video section of the http://calvario.org.br/ site.
    Thanks

  6. I was failing while I didn’t put the word “echo”.
    Thanks

  7. Daniel Balfour 2009/08/05 7:24 pm

    This is an excellent tutorial (and Jin’s as well!)
    Thank you for taking the the time and contributing to other people’s WordPress blogging experience!

  8. Lewis Litanzios 2009/10/27 2:23 pm

    You’ve done it again Jeff old son. First link out of Google I could make sense of (and has working code (2.8.5)).

    Cheers bro.

  9. Hello. I now it is possible to have a one stylesheet file per post. But im having too much troubles. I read this on smashing magazine

    I put this code in the header.php of my theme

    ID, "customStyles", true);
    if (!empty($customStyles)) { ?>
    <link rel="stylesheet" href="" type="text/css" media="screen" />

    Then in the custom field

    i put this

    Name: customStyles
    Value: all the href of my new stylesheet but i doesnt work.

    Can somebody help me please !

    Thanks in advance

  10. ldexterldesign 2009/12/15 3:03 am

    @Ruben Use the body classes output by WP on each individual page to hang your unique page styling off.

  11. Great post! very easy to follow and very well written. I was wondering how more than one image could be displayed in the same post using the same custom field input key? So, 2 image or more could be displayed in the active post… does this make sense, I have not found much on this and I like the simplicity of custom fields, but would be interested in adding more images to posts if needed.

    Thanks and keep up the great tutorial writing.

    Chad

  12. Jeff Starr 2010/01/09 9:33 pm

    Hi Chad, I think this should help you out:

    Awesome Image-Attachment Recipes for WordPress

    It covers many different techniques for including images attached to posts.

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 »
GA Pro: Add Google Analytics to WordPress like a pro.
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.