This is a tutorial for beginners, and we were all beginners once.

To a beginner I remember custom fields looking quite pointless. I couldn’t quite grasp what they were for.

Then, after building a few WordPress sites, I watched an excellent tutorial from Chris Coyier over at CSS Tricks and it really opened my eyes. There’s a link at the bottom of this post to Chris’s excellent video series. And that link was generated using a custom field.

To whet your appetite, here’s an example of a search function I built for THET using custom fields. You can select from three options and then WordPress will search through all the posts custom fields until it finds a match.

That’s a really powerful way to harness WordPress custom fields, but we’re going to start with something a little easier.

The project

In this tutorial, we’re going to stick with something simple. All you’ll need is some basic PHP, together with feeling comfortable working with some WordPress files; specifically single.php which you’ll find in http://your-wordpress-url.com/wp-content/themes/your-theme/single.php.

To keep things both easy and hopefully useful, we’re going to create a couple of custom fields which display a credit and a link to a flickr image. I’m using it in this post! The image at the top of the field (custom fields, gettit?!) came thanks to a flickr user called innoxiuss. And if you scroll to the bottom of this page you’ll see a credit that looks like this:

Well that credit is generated thanks to two custom fields and a little bit of php code.

What is a WordPress Custom Field?

Okay. So think of a custom field as a bit of data. It can be anything at all, as long as it’s an alpha numeric string that can be stored in the WordPress database. So a custom field is not an image, it’s the URL of the image.

A custom field has two properties, a name and a value.

For example, the name could be image and the value could be www.yoursite.com/image.jpg.

But here’s the thing: it doesn’t have to make that much sense. The name could be fruit and the value could be apple. And as pointless as that looks, there are instances where that information could come in useful.

Let’s take the real world example of the flickr credit on the bottom of this page. There are actually two custom fields in there. The first is the flickr user and the second is the URL of the photo.

Name: flickr_attribute_url
Value: http://www.flickr.com/photos/innoxiuss/2665404220/

Name: flickr_attribute_name
Value: innoxiuss

How to add a Custom Field

Custom fields are added on the Edit Post page, and it looks like this…

If you can’t see it, then scroll to the top and under ‘Screen Options’ make sure that ‘Custom Fields’ is ticked.

All you have to do is click on the ‘Enter new’ link (in blue) and enter a name for your data under ‘Name’.

Next enter your data’s value under ‘Value’.

Finally, click on the ‘Add Custom Field’ button and you’re done. This is what it might look like…

You can add as many custom fields as you like, and on some posts I have over 20. Here you can see I’ve added two, making sure that the names are unique.

And that’s it. You now have two custom fields each containing a snippet of data.

But without rolling up our selves and getting our hands dirty with some PHP, this isn’t going to do a thing.

Adding the PHP

Here’s the code we’ll be using. Have a read through and see if it makes sense…

Okay, let’s take a moment to go through the code.

First of all, make sure you have created the custom fields in your WordPress post, and that you have the names of the fields exactly right. After all, if there’s no custom field data there’s nothing to do!

We check for the data in the first line:

We use the WordPress function get_post_meta to grab the value for ‘flickr_attribute_name’. If there’s no data there then this statement will be null and the if won’t run. If there is something in that custom field then the code will carry on executing.

But hold on a minute, what’s all that other stuff? Well, the get_post_meta function has the following parameters:

We set our $post_id as the current post using $post->ID. Our $key is the name of the custom field which is ‘flickr_attribute_name’. And finally we set $single to true.

What is single? If it’s set to true it returns a single result as a string. If it’s set to false it returns multiple results as an array. We’ll get on to arrays in later tutorials, but for now we’re going to keep it simple. We only have one value for our flickr credit so we leave it as true.

So now we know we have some data, let’s carry on with the code. We put our content in a DIV so we can style it to our liking

And we also create two variables with our custom field data in. The get_post_meta function works exactly as we described it above.

Again, note that we set the $single parameter to true, because we know there is only one bit of data. How do we know this? Well, in this instance it’s because we’ve set the custom field up ourselves in the WordPress backend.

Finally, we throw together the rest of the HTML, and close off the if statement.

Bringing it together

So we have our custom fields in WordPress and we’ve entered some data into them. We’ve also created the snippet of easy PHP which’ll read this data and display it on the page.

But where does it go?

Well, for this snippet I’ve chosen to put it on the bottom of the single.php page in the wp-content folder, as this is the page that displays single posts.

On my page it comes just before the section, which itself is just before the comments bit. But you could put it anywhere you want.

Just boot up your favourite PHP editor (I like Expresso on the Mac and, predictably, Dreamweaver on the PC) and type in the code.

Save your page, upload, and you should have a lovely flickr photo credit.

What next?

Don’t have flickr photos on your page? Well then this could be a bit pointless. But remember, this tutorial should just give you a basic idea of how custom fields work. Sure, you could have put this flickr information in the post itself but as we’ll see, we can do all kinds of funky things once we have the ability to search custom fields and display data based on their contents.

In the mean time there is some further reading below. Oh, and the further reading is displayed from data in custom fields!

You need to install WordPress on a Windows machine running IIS. I’d never normally do this, but sometimes you just don’t have a choice.

There are plenty of links out there about how to do this, and the one I referred to most was How To Install WordPress on IIS 6.0. It is, more or less, straightforward.

However, there’s an issue with IIS and permalinks.The issue is that if you want to take advantage of the WordPress pretty permalinks, you have to suffer a folder in the path called ‘index.php’. So, instead of the rather lovely:

http://www.yourblog.com/yourcategories/the-best-post-in-the-world/

you have to grit your teeth and accept:

http://www.yourblog.com/index.php/yourcategories/the-best-post-in-the-world/

I don’t know why, I really don’t. I’m not that smart. But I did work out how to fix it. It’s easy enough, but you have to put a couple of rules in the ISAPI ReWrite Engine to deal with the quirks.

First we need to head into our WordPress admin tool, and go to Settings > Permalinks. There, you’ll see the craft insertion of /index.php/ in the links. We need to create a custom permalink and delete the index.php bit. Just like this…

Now save that off and head over to your .htaccess file – we need to weave some magic!

At the bottom of this post is the whole file, but the two lines I particularly want to point out are:

The second line works the juju. It takes the URL from the browser, shoves an /index.php/ into it, and displays the contents. For more on how and why this works, check out http://www.workingwith.me.uk/articles/scripting/mod_rewrite for the basics.

Now the first line is really important, because it tells the server not to do this if we’re in the admin section. If we remove this line, there are all kinds of problems reaching /wp-admin/index.php. Trust me.

I have two other lines in the following code which get rid of index.php from URLS, which stops the google duplicate content issue. They’re always worth having.

Finally, make sure that wherever your site is hosted, that the correct permissions are set on the wp-admin and wp-content directories and their sub-directories. You must have read/write/modify permissions set for internal user accounts.

If you implement these small tweaks, then your WordPress IIS install should work like a charm.

Good luck!

Here’s the code:

Thanks for watching, kids…

Well ain’t that the cutest thing! But what is it?

It’s the little .gif file that the WordPress Stats plug-in uses to monitor your page. It does so with some code like this…

…where the #’s are various characters. It’s all mystic WordPress voodoo which you don’t need to worry about.

Now I actually like the smiley face, but some people want to remove it from their blog. And it’s easy to do.

In wp-admin, head over to Appearance > Editor > style.css (or whatever your main style sheet is named). You then just add this bit of CSS:

There you have it! We’re just using plain and simple css to remove the smiley face from the screen, but still loading it so the page view gets counted.

So now you know how to remove the WordPress Stats smiley face. The question is, do you really want to?!

Does this all look a little strange? If so, check out part 1 and part 2 of this tutorial!

First, let’s look at the code…

function WordTweet_control() {
 
	// We need to grab any preset options
	$options = get_option("widget_WordTweet");
 
	// No options? No problem! We set them here.
	if (!is_array( $options )) {
		$options = array(
	  	'WordTweetTitle' => 'WordTweet',
	  	'username' => 'Username',
	  	'password' => 'Password',
	  	'tweets' => '1'
		);
	}
 
	// Is the user has set the options and clicked save,
	// Then we grab them using the $_POST function.
	if ($_POST['WordTweet-Submit']) {
		$options['WordTweetTitle'] =
		  htmlspecialchars($_POST['WordTweet-WidgetTitle']);
		$options['username'] =
		  htmlspecialchars($_POST['WordTweet-WidgetUsername']);
		$options['password'] =
		  htmlspecialchars($_POST['WordTweet-WidgetPassword']);
		$options['tweets'] =
		  htmlspecialchars($_POST['WordTweet-WidgetTweets']);
		// And we also update the options in the Wordpress Database
		update_option("widget_WordTweet", $options);
	}
 
	?>
	<p>
		<label for="WordTweet-WidgetTitle">Title:</label><br />
		<input type="text"
		  id="WordTweet-WidgetTitle"
		  name="WordTweet-WidgetTitle"
		  value="<?php echo $options['WordTweetTitle'];?>" />
		<br />
		<label for="WordTweet-WidgetUsername">Username:</label><br />
		<input type="text"
		  id="WordTweet-WidgetUsername"
		  name="WordTweet-WidgetUsername"
		  value="<?php echo $options['username'];?>" />
		<br />
		<label for="WordTweet-WidgetPassword">Password:</label><br />
		<input type="text"
		  id="WordTweet-WidgetPassword"
		  name="WordTweet-WidgetPassword"
		  value="<?php echo $options['password'];?>" />
		<br />
		<label for="WordTweet-WidgetTweets">No. of Tweets:</label><br />
		<input type="text"
		  id="WordTweet-WidgetTweets"
		  name="WordTweet-WidgetTweets"
		  value="<?php echo $options['tweets'];?>" />
		<input type="hidden"
		  id="WordTweet-Submit"
		  name="WordTweet-Submit"
		  value="1" />
	</p>
	<?php
}
 
function WordTweet_init() {
	// These are the Wordpress functions which will register the
	// Widget, and also the control - or options, to you and me.
	register_sidebar_widget('WordTweet', 'widget_WordTweet');
	register_widget_control('WordTweet', 'WordTweet_control');
}
 
add_action("plugins_loaded", "WordTweet_init");

This really should be nothing new, if you followed the tutorial on how to create a WordPress widget. We’re simply setting up the options for the Widgets page of the WordPress admin, and saving the options to the database with our update_option(“widget_WordTweet”, $options); command.

In part two, we added a piece of code to link to an external CSS stylesheet, like so…

// First we grab our CSS stylesheet. It's a really simple one, but it's good practice to
// keep this in a seperate file.
echo'<link href="' . get_bloginfo('url') . '/wp-content/plugins/WordTweet/WordTweet.css" rel="stylesheet" type="text/css" media="screen" />';

So now we just need to take a look at what’s in the stylesheet.

.WordTweet li {
	display:block;
	background-image:url(twitter.png);
	padding-left: 22px;
	background-repeat:no-repeat;
}

By displaying our li elements as a block it get’s rid of the bullet points which are the default. We set a background image to our Twitter ‘t’ (you can grab that in the full sourcecode download), and so we also have to pad the text from the left where this image is by 22px. Finally, we make sure this background isn’t repeated.

That’s it! By saving that file as an external CSS file you can have all kinds of fun with it. You might want to add a border-bottom and create a nice underlined effect. Whatever tickles your fancy.

Finally, some homework. This is a pretty basic implementation, and there are lots of things you can add to spice it up for your own site. Maybe you can try the following, all pretty easy with some basic php:

• Try writing a script to display “added x hours ago”, like here on the site.
• Try making the ‘@’ filtering out an option in the Widget settings.
• Try changing the CSS so the Tweets appear in speech bubbles, or add your own Twitter icon in a corner of the widget

You can download the full sourcecode, CSS and images from http://www.richardshepherd.com/downloads/WordTweet.zip. And as always if you have any questions please just drop me a comment.

$result = $t -> userTimeline($id=false, $count = ($options['tweets'] * 4), $since = false);

(If that looks strange, make sure you check out part 1 of this tutorial!)

We now have our Tweets stored in $result so we can just cycle through them and print them out in our widget. To do that we need the next bit of code.

Rather than explain each line after the code, I have heavily commented it which takes you through the process step-by-step…

// If there are no results, lets pop up a default message
if ($result===false) {
echo "Sorry, nobody's home! Back in five.";
 
// Success! We have Tweets! Let's display 'em!
} else {
 
// First we grab our CSS stylesheet. It's a really simple one, but it's good practice to
// keep this in a seperate file.
echo'<link href="' . get_bloginfo('url') . '/wp-content/plugins/WordTweet/WordTweet.css" rel="stylesheet" type="text/css" media="screen" />';
 
// We need a way to count the number of Tweets we display, so let's start a counter at '0'.
$iTweets = 0;
 
// The first piece of HTML. The <div> class 'WordTweet' is there for our CSS styling
// The <ul> unordered list is how we'll be displaying each Tweet
echo '<div class="WordTweet"><ul>';
 
// For each part of the array, in other words each Tweet, we grab the
// string and call it $tweet
foreach ($result as $tweet) {
// We're interested in the text within the Tweet, not the other
// information like date (until later!). Let's grab that and call it $message.
$message = (string)$tweet->text;
 
// Now I like to take our any Tweets beginning with '@', as these are replies specifically
// to other people. If you wanted you could take this bit out, but don't forget to remove the
// closing '}'
if (substr($message,0,1) != "@" && ($iTweets < $options['tweets']+1)) {
 
// make_clickable is a helpful WordPress function that takes things like email addresses
// and websites in a string of text and turns them into links. Ah, the joy of regular
// expressions!!
$message = make_clickable($message);
 
// I don't display the first, as it's in the header of my theme, so I skip the first Tweet
//by making sure that $iTweet is greater than 0.
if ($iTweets > 0) { // You could take this line out...
// Display the Tweet, nestled in a <li></li> tag
echo '<li>' . $message . '</li>';
} // ...but you'd need to remove this too!
 
// That's one Tweet down, so let's increase $iTweet by 1
// and move on to the next
$iTweets++;
 
} // End of the If statement
} // End of the foreach loop
 
// Finish up our HTML output
echo '</ol></div>';
 
} // End of the if ($result===false) statement
 
// And now that last bit of HTML from the WordPress Theme
echo $after_widget;
}

Make sense? Let’s take a look at two lines in a bit more detail.

echo'<link href="' . get_bloginfo('url') . '/wp-content/plugins/WordTweet/WordTweet.css" rel="stylesheet" type="text/css" media="screen" />';

get_bloginfo is a handy WordPress function which returns various useful pieces of information. For example, get_bloginfo(‘template_directory’) returns, you’ve guessed it, the URL of the template directory.

With get_bloginfo(‘url’) we are grabbing the blog URI which the user has set in Settings. We then just add in the path to the .css file, which we know is in the WordTweet directory.

Secondly,

if (substr($message,0,1) != "@" && ($iTweets < $options['tweets']+1)) {

So, (substr($message,0,1) is a way of grabbing a sub-string (part of a string) from our string $message. We are interested in the first character, because I want to know if it’s a ‘@’, so we add to parameters ’0,1′ The first parameter tells PHP where to start, and we start with the first character which is in position ’0′. The second parameter is how many characters we want, in our case just the ’1′.

We then check to see if this is NOT equal to ‘@’ with !=. If it’s NOT ‘@’ then it’s not a Twitter reply and so we can display this Tweet. But we have one more check to make!

The second part of that If statement checks to make sure we are only displaying the number of Tweets the user specified. Initially this was just set as $options['tweets'], but I had to change it to +1. Why? Because I’m not displaying the first Tweet (it appears in the header of my site) I need to start on Tweet 1, not Tweet 0 (the first in our array). Which means if I want to display 5 Tweets I actually have to loop through until 5 (rather than 4 – remember 0 to 4 is FIVE Tweets).

I hope that makes sense, as it’s rather convoluted. If your blog doesn’t display Tweets anywhere else, you can remove the && ($iTweets < $options['tweets']+1)) bit.

Right, that’s it for part 2. Part three will finish things off with the options and look at the css. It’s in the css that we add the Twitter logo. I’ll also suggest some further reading, and ways you can develop this simple script further.

Go to part 1 | Go to part 3

First things first, make sure you read and understand the How to Create a WordPress Widget Tutorial, as we’ll be building on that code. In fact, adding in the Twitter code is reasonably straightforward.

Twitter has a API we can use to grab all the details, but our life get easy if we use a prewritten PHP class that does some of the hard work for us. A couple are kicking around out there, but I’m going to work with the lightweight twitterPHP by David Billingham. It doesn’t include all the functionality of the Twitter API, but it’s got everything we need to kick off with.

So, we know how to create a Widget thanks to our earlier tutorial. What we now need to do is:

1. Start with the usual widget code
2. Send a call off to Twitter with our username and password
3. Ask Twitter for a certain number of Tweets
4. Display these Tweets in our widget
5. Finish up the widget code
6. Write the code for the WordPress widget options

And that’s it. So, without further ado, I give you WordTweet – my WordPress Twitter widget!

WordTweet

Our code starts off almost identical to the WordPress widget tutorial:

<?php
/*
Plugin Name: WordTweet
Plugin URI: http://www.richardshepherd.com
Description: A  widget that displays your Twitter Tweets
Author: Richard Shepherd
Version: v0.2
Author URI: http://www.richardshepherd.com
*/
 
function widget_WordTweet($args) {
 
	// First we grab the Wordpress theme args, which we
	// use to display the widget
	extract($args);
 
	// We also need to make sure we include the Twitter Library
    require_once 'twitter.class.php';
 
	// Now we sniff around to see if there are
	// any preset options
	$options = get_option("widget_WordTweet");
 
	// If no options have been set, we need to set them
	if (!is_array( $options )) {
		$options = array(
	  	'WordTweetTitle' => 'WordTweet',
	  	'username' => 'Username',
	  	'password' => 'Password',
		'tweets' => '1'
	  	);
	}
 
	// Display the widget!
	echo $before_widget;
	echo $before_title;
		echo $options['WordTweetTitle'];
	echo $after_title;

You’ll spot a couple of changes. First we include the PHP Twitter class, which we will make sure is in the same directory as the widget.

require_once 'twitter.class.php';

Secondly we have changed our options code a little bit, to take into account the new options we need.

	// If no options have been set, we need to set them
	if (!is_array( $options )) {
		$options = array(
	  	'WordTweetTitle' => 'WordTweet',
	  	'username' => 'Username',
	  	'password' => 'Password',
		'tweets' => '1'
	  	);
	}

Next up we use the Twitter class to get our Twitter feed:

    // Create a new Twitter object and query for direct messages
    $t = new twitter();
      $t->username = $options['username'];
      $t->password = $options['password'];
 
    // This is where we grab the string as $result, from the users
    // timeline, with a $count=1 so we only get the most recent
    $result = $t -> userTimeline($id=false, $count = ($options['tweets'] * 4), $since = false);

So, we create an object $t and tell it our username and password which we grabbed from the options a few lines earlier. This is all happening on the server so it’s relatively secure – no one will see this info in our sourcecode.

Okay, then we query Twitter with the following options:

1. userTimeline – the timeline for the user specified in $options['username']
2. $id=false – This is optional, and allows us to return the results to the Twitter username or id specified. We don’t use this option, and hence set it to false.
3. $count = ($options[‘tweets’ * 4) – Stick with me on this on, as the logic is a little convoluted. $count is simply the number of Tweets to grab. Now on my homepage I display the three most recent, so you might ask why we don’t simply put $count = 3. Good question! Well, as we’ll see in the next part of this tutorial I like to remove all my ‘@’ Tweets because they are normally directed at just one persona and so not always suitable for my homepage. However, it’s impossible to know how many ‘@’ Tweets there are in any given query until we’ve actually made the query. Make sense? It might be that my last five Tweets are all good. But it might be that four of them are ‘@’ Tweets and so that would only leave me one to display. So, I grab four times the number of Tweets I want, because I’m pretty sure that if I want to display three Tweets, if I get the last 12 there are probably at least three non ‘@’ Tweets in there. Why four times? Why not! It could be * 5 or * 10 if you wanted. For me, I’m happy that * 4 is enough, although we can also set this as an option if we want.
4. Finally, we have $since = false. We can put a HTTP formatted date in here and that means we’ll only grab Tweets after that date. For this tutorial we are going to leave that as false, but you might want to introduce a new option to set this to the last day, or the last week.

That’s enough for part one. Make sure you understand what we’ve done here, and also look through the twitter.class.php and make sense of what David Billingham has done.

In part two of this tutorial we’ll cycle through our Tweets and display them in our widget. See you then!

Go to part 2 | Go to part 3

I’m first going to go through the structure of a Widget, and then we’re going to get our hands dirty with some code.

A basic Widget has four main components:

1. The Widget Information
2. The Widget Itself
3. Any options for the Widget
4. Initialising/Registering the Widget

Widget Header
The Widget Information is just a bit of information at the top of the file which WordPress uses to describe the Widget. It might look like this…

/*
Plugin Name: A Simple WordPress Widget Tutorial
Plugin URI: http://www.richardshepherd.com
Description: Simple Widget Tutorial from RichardShepherd.com
Author: Richard Shepherd
Version: v1.0
Author URI: http://www.richardshepherd.com
*/

Everything there is fairly self explanatory. The URI (Uniform Resource Identifier) is just a fancy (and more correct) way of describing the URL. Don’t worry too much about that for now.

Widget Functions
After that header, we have three functions to write.

function widgetTutorial() {}
function widgetTutorial_control() {}
function widgetTutorial_init() {}

The first function is the Widget itself, the second is where we set and store the options, and the third kicks the whole thing off.

So, what can be in a Widget? Well anything you can write in PHP. Perhaps is a fun new application you’ve been tinkering with, or maybe just a way of displaying random photos. Whatever it is, we need to write the code and pop it in the WidgetTutorial() function.

Writing the Widget
For our purposes we are going to display a header and some text. Both items can be edited from the Manage > Widgets page in your wp-admin. This is a pretty pointless Widget, but hopefully it’ll open the doors to some fun development for you.

Our Widget function could simply be…

function widgetTutorial($args) {
  extract($args);
  echo $before_widget;
  echo $before_title;
  echo 'Hello World!'; // Our Title
  echo $after_title;
  echo 'This is the main Widget text.'; // The text.
  echo $after_widget;
}

You should be familiar with things like echo ‘Hello World’; but what are all those other bits and bobs?

Well, imagine that WordPress has hundreds upon hundreds of Themes. We need to make sure that your Widget will integrate properly with each and every one of them. When some talented designer puts together their theme, they include CSS definitions for Sidebar Widgets and, thanks to the magic of WordPress, we can access them easily. In fact, we don’t even have to see them. All we need is to drop in

extract($args);

and then we’ll grab the relevant variables from the $args array. In our case, there are four variables we’re interested in:

$before_widget, $before_title, $after_title, $after_widget;

You can even see that their order mirrors HTML tags. You could almost imagine them written as:

<widget>
 <title>
 </title>
</widget>

although of course that wouldn’t work at all!! So, we extract those variables which go on to define the layout and then start to put together the Widget using echo commands. It really is that simple.

Dynamic = Interesting
But that’s a static Widget which is, quite frankly, boring. What we’re interested in is setting up some options to make this puppy a bit more dynamic. Start introducing a bit of randomness, and you have a truly dynamic page – no two views are the same. So let’s have a look at how that Widget function changes to accommodate our new options:

function widget_widgetTutorial($args) {
// First we grab the Wordpress theme arguements,
// which we'll use to display the widget.
extract($args);
 
// Now we sniff around to see if there are
// any preset options
$options = get_option("widget_widgetTutorial");
 
// If no options have been set, we need to set them
if (!is_array( $options )) {
$options = array(
'title' => 'Widget Title',
'text' => 'Widget Text'
);
}
 
// Display the widget!
echo $before_widget;
echo $before_title;
echo $options['title'];
echo $after_title;
//Our Widget Content
echo $options['text'];
echo $after_widget;
}

It’s really not that different. All we’ve added is

$options = get_option("widgetTutorial");
if (!is_array( $options )) {
$options = array(
'title' => 'Widget Title',
'text' => 'Widget Text'
);
}

and

echo $options['title'];
echo $options['text'];

First we create an array called $options, and populate with our Widget options (we’ll learn how to set these later). get_option() is a WordPress function which returns all the options into our array.

Next we test to see if the array $options is empty. If it is, it means no options have been set and we have to make up some default values. We do that with if (!is_array( $options )). Where the ! changes ‘is array?’ to ‘is not array?’. If it isn’t, we create the array in the standard way and pop in some default variables. That’s fairly straightforward.

All we do next is output parts of the array in our widget, using echo $options['title']; and echo $options['text']; where ‘title’ and ‘text’ are the options we have previously set.

Make sense? I hope so. You can download the code from Part 1 (Right-click the link, and select “Save As”).

In part two of this tutorial, we’ll look at putting together the options screen. See you soon!