Thank goodness for jQuery! jQuery has a handy little function which allows us to load JSON data using an HTTP GET request, and then process the contents as an array. And with some natty CSS to square things up as a grid, I have nine random (ish) photos from our Flickr group displaying in a nice 3×3 grid.

See it in action.

The full commented code is at the bottom of this post, but let’s go through it bit by bit.

What is JSON?

Since we’re talking about Flickr, let’s use they’re definition:

“JSON, or JavaScript Object Notation, is a simple machine-readable data-interchange format, which makes constructing API applications in JavaScript easy (though it can be used from other languages too!). “

Which means what exactly? Well, it’s a lot like any other feed or data – like an RSS feed, for example. A typical Flick JSON response might look like this:

Which is not altogether too hard to digest. To see the whole feed from Talk On Travel have a look here.

All we need to do is get that feed in a way our javascript can use, and then use it. Enter, stage left, jQuery…

Create our object and fill it with data

So how can jQuery help us out? With the handy $.getJSON(url, [data], [callback]) command.

It’s simpliest method would be something like:

Which would grab the info from a json feed at www.example.com/yourjsonfeed.json and then execute a function called functionName.

Then, you’d have to create a function like so:

In which data is automatically populated with the json feed. Nice, eh?

So now we have our data object, we need to know how to grab stuff out of it. Again, this is pretty easy stuff. We use some dot syntax like:

Which says… in data, go to (the first) item, then go to the media bit and grab the m bit.

Scroll back to the top of this page, and in our example you’ll see that this would be ‘http://farm4.static.flickr.com/3037/3081564649_4a6569750c_m.jpg’.

You can probably work out then what item.title and item.link would give us. Armed with that, you can get any information you need from this feed. All we have to do now is display it!

Getting this feed onto the screen

Does that make sense so far? Hope so. If you get lost, check out the excellent jQuery documentation – the links for which are at the bottom of this post.

Let’s sew it all together in a really simple function that just cycles through all the images in the feed. By default, Flickr returns 20 images.

As I’ve commented the code, you should be able to work it out from here…

But those aren’t my photos!?

I know, I know. Have a look at that feed address once more…

http://api.flickr.com/services/feeds/groups_pool.gne?id=998875@N22&lang=en-us&format=json&jsoncallback=?

Spot the 998875@N22 bit? Well that’s the Flickr user ID for Talk On Travel, another blog that I look after. You need to put your own ID in that string.

I recommend using http://idgettr.com/ to find out easily!

Over to you

That’s a simple introduction to JSON and Flickr, and I hope it puts you on the right path.

For more details on JSON and jQuery, and with another example of how to get photos from a Flickr JSON feed, check out http://docs.jquery.com/Ajax/jQuery.getJSON.

To read up on the Flickr JSON object, head over to http://www.flickr.com/services/api/response.json.html.

You can see my code in action at http://www.richardshepherd.com/flickr.html. Check out the source code to see what it’s doing.

Obviously, you can do a lot more with this, but it’s just a basic implementation to get you started.

Good luck!

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