The Design Canopy

There are two basic steps to adding your own custom fields to WP Contact Manager: Creating the input through the WordPress admin area and adding functionality for the output in the theme’s PHP files. It’s not hard, and once you get the hang of it you’ll be surprised at what else you can do!

Before we dive into those two steps though, we’ll take a generic look at how the custom field output is accomplished.

Retrieving Custom Fields from the Database

Custom fields are retrieved from the database using the built-in get_post_meta() function. This function has three parameters:

1. The post ID from which to get the meta data,
2. the name of the custom field to retrieve,
3. and whether the resulting value of the custom field should be output as a single string or an array (either ‘true’ or ‘false’).

If the last parameter is confusing don’t let it deter you, just know that it will usually be set as true (single string). When you see this function in the theme’s PHP files it will look similar to the example below.

<?php echo get_post_meta($post->ID, "Office Phone", true); ?>

$post->ID

Since we are using the get_post_meta() function inside of the WordPress loop we can use $post->ID to pull the current post’s ID from the database. So this is our input for the first parameter.

"Office Phone"

The second parameter is the name of the custom field that we are retrieving from the database. (Remember that it must be exactly the same as the custom field’s Name that was created through the Custom Write Panel interface.)

true

As stated before, this tells the function to return the information it retrieves as a string.

We have to use the PHP echo command to display the results since the final value of the get_post_meta() function is a string.

To summarize let’s look at another example. In the upper right corner of WP Contact Manager there’s a list of four possible phone/fax/mobile numbers. The code for this is listed below in Figure 1.

You’ll notice that the first and third parameters for each function in Figure 1 are the same. The only parameter that changes is the name of the custom field that is being retrieved.

Creating Custom Custom Fields

My apologies for the repeating header, I couldn’t resist! Having familiarized yourself with the functionality of custom fields, the next step is creating your own and adding them to the theme. For this example we will add a field for a contact’s AIM screen name in the space to the right of the address block (see Figure 2).

Step 1: Adding the New Input

This step deals purely with the admin interface and has nothing to do with the theme’s PHP files.

If you are not familiar with creating custom fields through the Custom Write Panel interface, read STEP 5.2 in the tutorial on how to initially setup WP Contact Manager.

First we create another field through the Custom Write Panel interface; for the purposes of this tutorial we’ll name it AIM. You may choose any number you prefer for the order. If you followed the previous tutorial then you’ll remember we incremented the field orders in magnitudes of five so that you could add input fields between other fields later if you wished.

After you’ve created the new custom field via the CWP interface you will now see a new text box in the Add Contact interface. (Where it appears depends on the order number you assigned it.) So now we have a new field for every contact’s AIM screen name (if applicable). That completes STEP 1.

Step 2: Adding the New Output

Now that you have a new input box you need to tell the theme to output what you entered into that box. We do this with the built-in WordPress function get_post_meta() covered in the first part of this post.

Since the AIM screen name will only be displayed on the contact’s individual view (not the search results, tag lists, etc.) the only file to which we will add the get_post_meta() function will be single.php.

If you open the single.php file you will find the markup/code shown in Figure 3, beginning at line 39 and ending at line 41.

We will place the new markup and custom field output in the div (with the optional-fields class). Remember that we set the custom field Name as AIM; so when we use the get_post_meta() function we will use "AIM" as the second parameter. The new lines of markup/code are highlighted in Figure 4*.

Now when you view individual contacts there will be a place for AIM screen names. You can view this in the demo and in Figure 5.

(The class, site-subtitle, on the h3 tag is a class that is included in the theme’s style.css file.)

At this point we could stop and it would function properly; but there is the case that not everyone has an AIM screen name. So when a contact does not have any associated value for the AIM custom field, the output is blank (see Figure 6).

Luckily, since the get_post_meta() function returns the value as a string, we can do a simple logic test to determine whether or not the AIM screen name markup should be shown. The code for this is shown in Figure 7.

A couple points to note about the code in Figure 7

• The ” in line 5 is actually two single quotes, but WordPress converts them to the typographically correct version. So if you copy the code directly make sure you convert them to single quotes.
• You only have to use the get_post_meta() function once since it’s stored in the string—$aim_screen_name—going forward.

Questions?

If you have any further questions please leave them in the new forum for WP Contact Manager. Thanks!

UPDATE: There is some additional work required when displaying Custom Write Panel Check Box Lists.