Tutorial: Wordpress Custom Field

Beside the body of the article, it is possible to add other data in Wordpress and display them at the desired location beside the text. In fact this custom field can be associated with a script and so allow to develop an automated display.

Custom fields are resources defined by the author of the blog, which can be used in an article or not.

We define a field in the Writing section of the administration interface. The definition of a custom field can be used once or several times in one article and then produce one or more displays. It may not be used at all for an article.

This article is based on the 2.3.2 version of Wordpress and further versions.

Defining a custom field

It is from the edit page that can be added a custom field to a post. The definition of the field is similar to that of a category, it can be done locally in an article but becomes global for the blog. At the bottom of page can be found the "Custom fields" form...

The author defines a field by a pair key/value.
- The key is used to identify the field and
- The value contains data displayed beside the article, or used for the display.

Thus when creating or modifying a post:
- a key already created may be reused or,
- a new key may be created.
And in both cases a value is set for the post.
Each key once created belongs to the database and can be used with any article.

Reuse of the custom field

From the moment of the creation of a field, when an article is created or modified, a form at the bottom of the page shows a list of keywords created for custom fields. We choose a key and assign it a value for the current article.

The custom field form actually is an interface for passing values to a script, as discussed below.

How to display the contents of the custom field

It is not expected that the field appears automatically, since it depends on the chosen template, and also because the site administrator may want to select the location where to display this field.

To do this we must edit the main template, through the menu Theme/Theme editor and select the file for the body of the article, and insert in The loop the the_meta() function: 

<?php the_meta(); ?>

For the classic template, the source code might look like this: 

<div class="storycontent">
<?php the_content(__('(more...)')); ?>
</div>

<?php the_meta(); ?> 

<div class="feedback">
...

It is only a possible placement among others.

HTML code of the page

Suppose that the key is: "quotation" and the value is "Hello World!" The the_meta () function retrieves the key and value from the database, and provides this information to the display engine that integrates them into the page in HTML.
Watch the source code of the page to see how this integration is made, it has the following form: 

<ul class='post-meta'>
<li>
    <span class='post-meta-key'>quotation:</span> 
    Hello World!</li>
</ul>

The classes post-meta and post-meta-meta-key have predefined descriptors in the CSS file. You may change the style file (style.css for the classic template), to display the contents as desired.

For example, you can not display the key with this descriptor: 

.post-meta-key: { display:none; }

And write the text in green: 

.post-meta: { color:green; }

But the display of custom fields can be defined more efficiently by switching to programming, and using the key and value data in a script.

Programming custom fields

Using PHP and some internal functions dedicated to custom fields, it is possible to achieve a personal implementation.

In this case, we does not use the standard the_meta() function, but rather a PHP script written from these dedicated functions, that are:

  1. get_post_custom()
    Returns the list of key/value pairs for the post.
  2. get_post_custom_keys()
    Return the keys.
  3. get_post_custom_values($key)
    Returns the value for a given key and for the post.
  4. get_post_meta($id, $key, $format = false)
    Alternative function that returns the value from the post ID and the key.
    The post number $id is obtained automatically with the predefined variable $post->ID.
    The $key key is a litteral text or a variable containing a string obtained by the previous functions.
    The false value for the $format variable, commands to return an array, and true, a string.

Once in possession of values that was entered by the author, we apply a processing defined by the PHP script. See in the example below...

Example of a simple script associated with a custom field

We will replace in the loop in the main file the function the_meta() by a script that displays only the value and not the key. 

<?php 
   $value = get_post_meta($post->ID, "quotation", true);
   echo "<ul class='post-meta' >";
   echo "<li>";
   echo $value;
   echo "</li>";
   echo "</ul>";  
?>

This script, which has a demonstrative goal only, uses the default style attributes and displays simply the value given in the editing interface by the blog author.

Conclusion

This tutorial provides the foundation for the use of custom fields. We will see in a subsequent article how to make something more sophisticated for his blog, such as a tag cloud centered around subject of the article.