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!

It’s a widget I have developed for WordPress which allows you to include your Flickr photos in your blog, and display them with the rather funky Slimbox tool. Click on one of the photos and see what I mean. Slimbox, as well as looking great, allows you to navigate back and forth if you hover your mouse over the top left and top right of the picture.

The widget itself has a number of configurable options which are easy to set up and change. At the moment they include:

• API Key
• API Secret
• Set ID
• Number of photos
• Photos per row

Before I release the widget I’ll be adding some more options, including the Flickr username and an ability to style how the thumbnails are displayed. At the moment they are just 50px squares.

Stayed tuned for more phpFlickr fun.