Meyerweb: WordPress Tools: MW Latest Tweet

WordPress Tools: MW Latest Tweet

Version: 1.0
Date: 27 May 2008
Download: mw_latest_tweet.zip

Version: 1.1b2 (note this is a beta, with a file structure slightly different than that described below and three new features not documented here)
Date: 8 December 2008
Download: mw_latest_tweet_11b2.zip

Installation

When you unzip the archive, you'll find the plugin file mw_latest_tweet.php and a directory called mw_latest_tweet containing the files mw_lt_admin.css, which controls the presentation of the settings page; and Michal Migurski's json.php, which provides JSON functionality if your server doesn't have PHP5 (like mine). Thanks, Michal!

Upload all that to your wp-plugins directory, or upload the archive and unzip it there if you prefer that, and then go to the Plugins page and activate the plugin. Hooray! But you're not ready to go yet, because two things have to happen, although they can happen in either order.

Go the place you want to have your latest tweet appear in your template and add the following to the markup:

<?php if(function_exists('_mw_lt_update')) _mw_lt_update(); ?>

This if pattern is recommended because that way if you ever disable the plugin or it breaks or something else goes wrong, your site won't bomb out on a PHP "function does not exist" error.

That's the only function there is, really. Everything else is controlled through the settings page.
In order to start pulling tweets, you need to supply your Twitter "screen name". That's the last part of your Twitter home page's URL; that is, if your Twitter home is http://twitter.com/meyerweb, then not only are you me, but your screen name is meyerweb. Fill that into the first field. If you want to roll right away, then update the settings. Now, the next time you (or anyone) load a page that calls _mw_lt_update(), the latest tweets will be pulled from Twitter and the latest of them will be cached. Joy!

Now a few words on the other options. The cache interval is how long the plugin will wait since the last time it downloaded tweets before doing so again. Long cache intervals means you might not have the absolutely most latest tweet, especially if you're one of those tweet-every-twenty-seconds Scoble types. If you go with too short a cache interval, then just about every visitor to your site will trigger a call to Twitter.

You may be aware that Twitter does not always have the fastest response times nor the highest levels of uptime. That's actually the reason for the caching; that way, even if Twitter is down, something will be displayed. Still, if the plugin triggers a check because it's past the cache interval, there's a wait while the plugin tries to talk to twitter.com, which makes your site look slow. Also, if you hit Twitter too often in an hour, it will stop responding to your queries. So choose an interval that works for you, but choose wisely.

For the rest, you have the option of showing the time of the tweet just as Twitter reports it (which is in some funky format that not even PHP's strtotime() understands; thanks for ignoring ISO 8601 and RFC 2822, Twitter!) or in "human" time intervals, describing how long ago the tweet was made. Then you can decide whether you want to show "@reply" tweets or not.

Finally, you can define the XHTML and content that the plugin returns. If you just leave it alone or set it to be completely empty, the plugin will return the text of the tweet and nothing else. What you can do is define all the XHTML to be placed. If you do it that way, if there's a failure to return a tweet, none of the markup will come back. That means you don't have a box or something with no text in it on your home page. The whole thing just silently removes itself.

Of course, to do that, you'll need to know about the replacement strings that can be used in that field.

Replacement String Reference

These are all the bits of data returned via the Twitter API when you make a JSON call. Most of them are trivial or useless for the intended purpose of this plugin, but hey, they're here if you want 'em.

Note that the all-uppercase format of these strings is required. If you put in %%text%% instead of %%TEXT%%, you're going to get back the %%text%% instead of the text of the tweet.

%%TEXT%%: The actual tweet, such as "Headed to lunch now" or "Just saw 'Indiana Jones and the Kingdom of the Crystal Skull' -- OMGWTFBBQSAUCERMEN?!?!?!?". Like that.
%%CREATED_AT%%: The time the tweet was received by Twitter. If you have the "human time" option set to "Yes", the result will be in that fashion (e.g., "six minutes ago"). If it's set to "No", you'll get the raw time string reported by Twitter, which is sort of but not quite the RFC 2822 format.
%%ID%%: The status ID of the tweet. For example, if the tweet's URL is http://twitter.com/meyerweb/statuses/817596203, then the status ID is 817596203.
%%SOURCE%%: The place from which the tweet was sent. For example, if you post a tweet by going to your page on twitter.com and using the big textarea there, then the source will be "web". Note that this can be a whole set of XHTML. For example, the source value for posts from Twitterrific is (at least as of this writing) <a href=\"http:\/\/iconfactory.com\/software\/twitterrific\">twitterrific<\/a>.
%%IN_REPLY_TO_STATUS_ID%%: If the tweet is in reply to someone else's tweet, this is the ID (status number) of that someone else's tweet. Thus, if your tweet responded to http://twitter.com/meyerweb/statuses/817596203, then this value is 817596203.
%%IN_REPLY_TO_USER_ID%%: If the tweet is in reply to someone else's tweet, this is the ID of that someone else. This is their numeric ID, not their "screen name".
%%USER_NAME%%: Your name; e.g., "Eric A. Meyer".
%%USER_SCREEN_NAME%%: Your account name; e.g., "meyerweb".
%%USER_FOLLOWERS_COUNT%%: The number of people following you on Twitter.
%%USER_PROFILE_IMAGE_URL%%: If you have a profile image, then this is its URL.
%%USER_DESCRIPTION%%: The "describe yourself in 160 characters or less" biographical information from your Twitter settings.
%%USER_URL%%: The "More Info URL" you gave in your Twitter settings; e.g., "http://meyerweb.com/".
%%USER_LOCATION%%: Your geographic location, assuming you gave it to Twitter in the first place.
%%USER_ID%%: The numeric ID of the your account.

For those who are programming-minded, here's a single tweet from the JSON file Twitter hands over, lightly edited and reformatted to make reading it easier.

"truncated":false,
"in_reply_to_user_id":null,
"in_reply_to_status_id":null,
"source":"<a href=\"http:\/\/iconfactory.com\/software\/twitterrific\">twitterrific<\/a>",
"id":817596203,
"user":
     "name":"Eric A. Meyer",
     "description":"Web standards | (X)HTML | CSS | microformats | community | writing | speaking | signing man.",
     "url":"http:\/\/meyerweb.com\/",
     "screen_name":"meyerweb",
     "id":646533,
     "location":"USA",
     "protected":false,
     "followers_count":2880,
     "profile_image_url":
        "http:\/\/s3.amazonaws.com\/twitter_production\/profile_images\/19322632\/eric-mystery_normal.jpg"
"text":"My needs : TwitterTools :: parking violation : Peacekeeper MX",
"favorited":false,
"created_at":"Thu May 22 17:13:57 +0000 2008"