How to Embed a Tweet in WordPress: a Complete oEmbed Tutorial « planetOzh

A few days ago, Twitter published a new tool that lets you embed a tweet on your site, simplifying the old school way: take a screenshot, crop the picture, upload it, embed it.

The problem is: this Twitter tool is way too lame. Basically you need to cut and paste a lengthy code snippet full of HTML and CSS. How ugly. Compared to the way you can embed a Youtube video in WordPress (just pasting a video URL, on its own line) this is seriously cumbersome.

Hey, wouldn't it be cool if you can embed a tweet just as easily? You would just paste its URL and let WordPress transforms it into a nicely presented tweet with links and everything? OK, let's do a plugin for this. And guess what, it's going to be fairly easy, using WordPress' oEmbed API implementation.

What is oEmbed

When you paste a Youtube video URL, raw (not hyperlinked) and on its own line, WordPress transforms it into an embedded video. Why? Basically, there's something in WordPress that says "every time you see a URL like http://www.youtube.com/watch?v=*, ask http://www.youtube.com/oembed what to do with it".

In short, oEmbed is a simple API that lets you define a URL pattern (used by a consumer) and the URL of a script (the provider) that will generate a clean HTLM out of it.

Twitter does not support (yet) oEmbed, so we will have to handle this on our own: transform a WordPress blog into a oEmbed provider.

Register your blog as an oEmbed provider

First, let's register our blog as an oEmbed provider, to replace all URLs like http://twitter.com/ozh/status/13156561 into a cool piece of HTML. If you can breathe and walk at the same time, you're qualified to do this: all we need is a single function call. The function to be used here is wp_oembed_add_provider( $pattern, $url_of_service).

OK, so far, we're telling WP that everytime something looks like http://twitter.com/*/status/*, it will have to ask yourblog.com/blog/?ozh_tweet=1 what to do with it.

Catch URLs that will contain ?ozh_tweet=1

Since we're now expecting WP to do something particular when called with ?ozh_tweet=1, we have to hijack this URL:

So, at this point, every time WP sees a line matching http://twitter.com/*/status/*, it will ask yourblog.com/blog/?ozh_tweet=1&url=the_tweet_url&some_other_var=... what to do with it. So, what to do with it?

Handling the oEmbed request itself

Now for the fun part: the function that handles the oEmbed request and return the expected formatted output.

Basically, we're going to:

1. Guess the tweet id
2. Poll the Twitter API for information about this tweet, get a JSON response
3. Parse the JSON response, make something pretty with this it
4. Return that pretty thing into a JSON response

Vamos, muchachos:

And… That's it. Now just paste a tweet URL and let WordPress do the job. For your convenience, get the whole plugin we've just dissected in a single file

Further improvements and remarks

This simple "proof of concept" plugin returns very basic HTML, you'd need to make it prettier (use the tweet background, CSS style it). Just modify the "$html =" starting at line 44 or, even cooler, add an interface to the plugin where you can define a template for the tweet output. If you want some inspiration, I do something like this in my plugin Better Feed where the user can customize feed item footer with a simple templating system.

When WordPress makes an oEmbed request, it does it once and stores its result in the postmeta table. Twitter has that feature we all know and don't care about any longer: unreliability. Notice the timeout parameter I've added to the remote request (line 21), this is really needed. Still, if you blog cannot fetch the tweet from Twitter's API, it will store a dummy postmeta entry ({{unknown}}) and won't replace the tweet URL. A proper plugin should test for the postmeta value and re-poll the Twitter API if applicable.

Twitter does not support oEmbed, but another site does it for them: Ooh Embed. So, technically, a plugin to embed tweets using the oEmbed API would require just three lines, register oohembed.com as a producer. But that wouldn't be fun :) (and I don't know how reliable is oohembed.com)

Technically again, you could use more efficiently function wp_embed_register_handler() to deal with the oEmbed request without having to sending an extra HTTP request to your own site. But that would probably make a confusing example of the general mechanism of the API, with a consumer sending a request to a producer.

Any other comment or idea of something cool to do with Twitter and oEmbed? Use the comment form belllowwww