{"id":1398,"date":"2010-05-07T23:21:52","date_gmt":"2010-05-07T21:21:52","guid":{"rendered":"http:\/\/planetozh.com\/blog\/?p=1398"},"modified":"2010-05-08T01:06:57","modified_gmt":"2010-05-07T23:06:57","slug":"how-to-embed-a-tweet-in-wordpress-a-complete-oembed-tutorial","status":"publish","type":"post","link":"https:\/\/planetozh.com\/blog\/2010\/05\/how-to-embed-a-tweet-in-wordpress-a-complete-oembed-tutorial\/","title":{"rendered":"How to Embed a Tweet in WordPress: a Complete oEmbed Tutorial"},"content":{"rendered":"

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

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.<\/p>\n

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.<\/p>\n

\"\"
\n<\/p>\n

What is oEmbed<\/h2>\n

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=*<\/tt>, ask http:\/\/www.youtube.com\/oembed<\/tt> what to do with it".<\/p>\n

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

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

Register your blog as an oEmbed provider<\/h2>\n

First, let's register our blog as an oEmbed provider, to replace all URLs like http:\/\/twitter.com\/ozh\/status\/13156561<\/tt> 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)<\/tt>.<\/p>\n

\n\n\t\t
\n\n\t\t
\n\t\t\t\t\t\t< View plain text<\/span> ><\/a>\n\t\t\t\t\t<\/div>\n\n\t\t
php<\/div>\n\n\t\t\n\t\t
\n\n\t<\/div>\n\t\n\t
\n\t\t
  1. \/\/ Return the internal URL that will handle the oEmbed requests (ie yourblog.com\/blog\/?ozh_tweet=1)<\/span><\/div><\/li>\n
  2. function<\/span> ozh_tweetembed_internal_oembed_url(<\/span>)<\/span> {<\/span><\/div><\/li>\n
  3.     return<\/span> trailingslashit(<\/span> home_url(<\/span>)<\/span> )<\/span> .<\/span> '?ozh_tweet=1'<\/span>;<\/span><\/div><\/li>\n
  4. }<\/span><\/div><\/li>\n
  5.  <\/div><\/li>\n
  6. \/\/ Register this internal URL as an oEmbed provider for twitter URLs<\/span><\/div><\/li>\n
  7. function<\/span> ozh_tweetembed_add_oembed_provider(<\/span>)<\/span> {<\/span><\/div><\/li>\n
  8.     \/\/ http:\/\/twitter.com\/ozh\/statuses\/1234567<\/span><\/div><\/li>\n
  9.     wp_oembed_add_provider(<\/span> 'http:\/\/twitter.com\/*\/status\/*'<\/span>,<\/span> ozh_tweetembed_internal_oembed_url(<\/span>)<\/span> )<\/span>;<\/span><\/div><\/li>\n
  10. }<\/span><\/div><\/li>\n
  11. add_action(<\/span> 'init'<\/span>,<\/span> 'ozh_tweetembed_add_oembed_provider'<\/span> )<\/span>;<\/span><\/div><\/li>\n<\/ol>\t<\/div>\n\n<\/div>\n\n

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

    Catch URLs that will contain ?ozh_tweet=1<\/h2>\n

    Since we're now expecting WP to do something particular when called with ?ozh_tweet=1<\/tt>, we have to hijack this URL:<\/p>\n

    \n\n\t\t
    \n\n\t\t
    \n\t\t\t\t\t\t< View plain text<\/span> ><\/a>\n\t\t\t\t\t<\/div>\n\n\t\t
    php<\/div>\n\n\t\t\n\t\t
    \n\n\t<\/div>\n\t\n\t
    \n\t\t
    1. \/\/ Register 'ozh_tweet' as a query var so we can check if ?ozh_tweet=1<\/span><\/div><\/li>\n
    2. function<\/span> ozh_tweetembed_add_tweet_query_var(<\/span> $query_vars<\/span> )<\/span> {<\/span><\/div><\/li>\n
    3.     $query_vars<\/span>[<\/span>]<\/span> =<\/span> 'ozh_tweet'<\/span>;<\/span><\/div><\/li>\n
    4.     return<\/span> $query_vars<\/span>;<\/span><\/div><\/li>\n
    5. }<\/span><\/div><\/li>\n
    6. add_filter(<\/span>'query_vars'<\/span>,<\/span> 'ozh_tweetembed_add_tweet_query_var'<\/span>)<\/span>;<\/span><\/div><\/li>\n
    7.  <\/div><\/li>\n
    8. \/\/ As early as possible, check for query var 'ozh_tweet' and maybe shortcut everything<\/span><\/div><\/li>\n
    9. function<\/span> ozh_tweetembed_get_tweet_query_var(<\/span>)<\/span> {<\/span><\/div><\/li>\n
    10.     $tweet<\/span> =<\/span> get_query_var(<\/span> 'ozh_tweet'<\/span> )<\/span>;<\/span><\/div><\/li>\n
    11.     if<\/span>(<\/span> $tweet<\/span> )<\/span> {<\/span><\/div><\/li>\n
    12.         \/\/ Make something with the oEmbed request<\/span><\/div><\/li>\n
    13.         ozh_tweetembed_handle_oembed_request(<\/span>)<\/span>;<\/span><\/div><\/li>\n
    14.         \/\/ Now die, we don't want a blog page<\/span><\/div><\/li>\n
    15.         die<\/span>(<\/span>)<\/span>;<\/span><\/div><\/li>\n
    16.     }<\/span><\/div><\/li>\n
    17. }<\/span><\/div><\/li>\n
    18. add_action(<\/span> 'template_redirect'<\/span>,<\/span> 'ozh_tweetembed_get_tweet_query_var'<\/span> )<\/span>;<\/span><\/div><\/li>\n<\/ol>\t<\/div>\n\n<\/div>\n\n

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

      Handling the oEmbed request itself<\/h2>\n

      Now for the fun part: the function that handles the oEmbed request and return the expected formatted output.<\/p>\n

      Basically, we're going to:<\/p>\n

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

        Vamos, muchachos:<\/p>\n

        \n\n\t\t
        \n\n\t\t
        \n\t\t\t\t\t\t< View plain text<\/span> ><\/a>\n\t\t\t\t\t<\/div>\n\n\t\t
        php<\/div>\n\n\t\t\n\t\t
        \n\n\t<\/div>\n\t\n\t
        \n\t\t
        1. \/\/ Handle the oEmbed requests<\/span><\/div><\/li>\n
        2. \/\/ The oEmbed request is something like:<\/span><\/div><\/li>\n
        3. \/\/ yourblog.com\/blog\/?ozh_tweet=1&url=http:\/\/twitter.com\/ozh\/statuses\/123456&...<\/span><\/div><\/li>\n
        4. \/\/<\/span><\/div><\/li>\n
        5. function<\/span> ozh_tweetembed_handle_oembed_request(<\/span>)<\/span> {<\/span><\/div><\/li>\n
        6.     $url<\/span> =<\/span> esc_url(<\/span> $_GET<\/span>[<\/span>'url'<\/span>]<\/span> )<\/span>;<\/span><\/div><\/li>\n
        7.     if<\/span>(<\/span> !<\/span>$url<\/span> )<\/span><\/div><\/li>\n
        8.         die<\/span>(<\/span>'URL missing'<\/span>)<\/span>;<\/span><\/div><\/li>\n
        9.     <\/div><\/li>\n
        10.     preg_match<\/span>(<\/span> '!http:\/\/twitter.com\/([^\/]+)\/status\/(\\d+)!'<\/span>,<\/span> $url<\/span>,<\/span> $matches<\/span> )<\/span>;<\/span><\/div><\/li>\n
        11.     $author<\/span>  =<\/span> $matches<\/span>[<\/span>1<\/span>]<\/span>;<\/span><\/div><\/li>\n
        12.     $tweetid<\/span> =<\/span> $matches<\/span>[<\/span>2<\/span>]<\/span>;<\/span><\/div><\/li>\n
        13.     unset<\/span>(<\/span> $matches<\/span> )<\/span>;<\/span><\/div><\/li>\n
        14.     <\/div><\/li>\n
        15.     \/\/ From this point, we fetch content from Twitter and print a JSON string.<\/span><\/div><\/li>\n
        16.     \/\/ If something goes wrong (like, Twitter unreachable) then we'll simply print anything but JSON<\/span><\/div><\/li>\n
        17.     \/\/ and let WP handle the response.<\/span><\/div><\/li>\n
        18.     <\/div><\/li>\n
        19.     \/\/ fetch http:\/\/api.twitter.com\/1\/statuses\/show\/$tweet.json<\/span><\/div><\/li>\n
        20.     $apiurl<\/span> =<\/span> 'http:\/\/api.twitter.com\/1\/statuses\/show\/'<\/span>.<\/span>$tweetid<\/span>.<\/span>'.json'<\/span>;<\/span><\/div><\/li>\n
        21.     if<\/span> (<\/span> !<\/span>$result<\/span> =<\/span> wp_remote_retrieve_body(<\/span> wp_remote_get(<\/span> $apiurl<\/span>,<\/span> array<\/span>(<\/span>'timeout'<\/span> =><\/span> 15<\/span>)<\/span> )<\/span> )<\/span> )<\/span><\/div><\/li>\n
        22.         die<\/span>(<\/span> "could not fetch $apiurl<\/span>"<\/span> )<\/span>;<\/span><\/div><\/li>\n
        23.  <\/div><\/li>\n
        24.     \/\/ Check that JSON is well formed<\/span><\/div><\/li>\n
        25.     $result<\/span> =<\/span> trim<\/span>(<\/span> $result<\/span> )<\/span>;<\/span><\/div><\/li>\n
        26.     if<\/span> (<\/span> !<\/span>$data<\/span> =<\/span> json_decode<\/span>(<\/span>$result<\/span>)<\/span> )<\/span><\/div><\/li>\n
        27.         die<\/span>(<\/span> "Data was not JSON"<\/span> )<\/span>;<\/span><\/div><\/li>\n
        28.     <\/div><\/li>\n
        29.     \/\/ Now extract a few variables from the $data object<\/span><\/div><\/li>\n
        30.     $text<\/span> =<\/span> $data<\/span>-><\/span>text<\/span>;<\/span><\/div><\/li>\n
        31.     $created_at<\/span> =<\/span> date<\/span>(<\/span>'d M Y g:i a'<\/span>,<\/span> strtotime<\/span>(<\/span> $data<\/span>-><\/span>created_at<\/span> )<\/span> )<\/span>;<\/span><\/div><\/li>\n
        32.     if<\/span>(<\/span> !<\/span>empty<\/span>(<\/span>$data<\/span>-><\/span>source<\/span>)<\/span> )<\/span><\/div><\/li>\n
        33.         $source<\/span> =<\/span> 'via '<\/span>.<\/span>$data<\/span>-><\/span>source<\/span>;<\/span><\/div><\/li>\n
        34.     if<\/span>(<\/span> !<\/span>empty<\/span>(<\/span>$data<\/span>-><\/span>in_reply_to_screen_name<\/span>)<\/span> )<\/span> {<\/span><\/div><\/li>\n
        35.         $in_reply_to_screen_name<\/span> =<\/span> $data<\/span>-><\/span>in_reply_to_screen_name<\/span>;<\/span><\/div><\/li>\n
        36.         $in_reply_to_status_id<\/span>   =<\/span> $data<\/span>-><\/span>in_reply_to_status_id<\/span>;<\/span><\/div><\/li>\n
        37.         $inreply<\/span> =<\/span> "in reply to <a href='http:\/\/twitter.com\/$in_reply_to_screen_name<\/span>\/status\/$in_reply_to_status_id<\/span>'>@$in_reply_to_screen_name<\/span><\/a>"<\/span>;<\/span><\/div><\/li>\n
        38.     }<\/span><\/div><\/li>\n
        39.     $name<\/span> =<\/span> $data<\/span>-><\/span>user<\/span>-><\/span>name<\/span>;<\/span><\/div><\/li>\n
        40.     $screen_name<\/span> =<\/span> $data<\/span>-><\/span>user<\/span>-><\/span>screen_name<\/span>;<\/span><\/div><\/li>\n
        41.     $profile_image<\/span> =<\/span> $data<\/span>-><\/span>user<\/span>-><\/span>profile_image_url<\/span>;<\/span><\/div><\/li>\n
        42.     <\/div><\/li>\n
        43.     \/\/ Make up some HTML with the tweet info<\/span><\/div><\/li>\n
        44.     $html<\/span> =<\/span> <<<HTML<\/span><\/div><\/li>\n
        45. <div class="tweet"><\/span><\/div><\/li>\n
        46.     <div class="text">$text<\/div><\/span><\/div><\/li>\n
        47.     <div class="meta">$created_at $source $inreply<\/div><\/span><\/div><\/li>\n
        48.     <hr\/><\/span><\/div><\/li>\n
        49.     <div class="pic"><a href="http:\/\/twitter.com\/$screen_name"><img src="$profile_image">$name<\/a><\/div><\/span><\/div><\/li>\n
        50. <\/div><\/span><\/div><\/li>\n
        51. HTML<\/span>;<\/span><\/div><\/li>\n
        52.  <\/div><\/li>\n
        53.     \/\/ Put everything into a regular array<\/span><\/div><\/li>\n
        54.     $json<\/span> =<\/span> array<\/span>(<\/span><\/div><\/li>\n
        55.         'version'<\/span> =><\/span> '1.0'<\/span>,<\/span><\/div><\/li>\n
        56.         'type'<\/span>    =><\/span> 'rich'<\/span>,<\/span><\/div><\/li>\n
        57.         'width'<\/span>   =><\/span> 1337<\/span>,<\/span> \/\/ this parameter is mandatory according to the oEmbed specs, but we're not using it<\/span><\/div><\/li>\n
        58.         'height'<\/span>  =><\/span> 1337<\/span>,<\/span> \/\/ same.<\/span><\/div><\/li>\n
        59.         'html'<\/span>    =><\/span> trim<\/span>(<\/span> $html<\/span> )<\/span>,<\/span><\/div><\/li>\n
        60.     )<\/span>;<\/span><\/div><\/li>\n
        61.     <\/div><\/li>\n
        62.     \/\/ Now output a JSON response   <\/span><\/div><\/li>\n
        63.     header<\/span>(<\/span>'Cache-Control: no-cache, must-revalidate'<\/span>)<\/span>;<\/span><\/div><\/li>\n
        64.     header<\/span>(<\/span>'Expires: Mon, 26 Jul 1997 05:00:00 GMT'<\/span>)<\/span>;<\/span><\/div><\/li>\n
        65.     header<\/span>(<\/span>'Content-type: application\/json'<\/span>)<\/span>;<\/span><\/div><\/li>\n
        66.     header<\/span>(<\/span>'Content-Disposition: attachment; filename="oembed.json"'<\/span>)<\/span>;<\/span><\/div><\/li>\n
        67.     echo<\/span> json_encode<\/span>(<\/span> $json<\/span> )<\/span>;<\/span><\/div><\/li>\n
        68. }<\/span><\/div><\/li>\n<\/ol>\t<\/div>\n\n<\/div>\n\n

          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<\/p>\n

          \nDownload the plugin ozh-oembed-tweet.php.txt<\/a>
          \n(save as .php then put in your plugins folder)\n<\/div>\n

          Further improvements and remarks<\/h2>\n

          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<\/a> where the user can customize feed item footer with a simple templating system.<\/p>\n

          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}}<\/tt>) and won't replace the tweet URL. A proper plugin should test for the postmeta value and re-poll the Twitter API if applicable.<\/p>\n

          Twitter does not support oEmbed, but another site does it for them: Ooh Embed<\/a>. 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)<\/p>\n

          Technically again, you could use more efficiently function wp_embed_register_handler()<\/tt> 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.<\/p>\n

          Any other comment or idea of something cool to do with Twitter and oEmbed? Use the comment form belllowwww<\/span><\/p>\n","protected":false},"excerpt":{"rendered":"

          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\u2026<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[21],"tags":[367,371,85,292,245],"class_list":["post-1398","post","type-post","status-publish","format-standard","hentry","category-published","tag-how-to","tag-oembed","tag-plugins","tag-twitter","tag-wordpress"],"_links":{"self":[{"href":"https:\/\/planetozh.com\/blog\/wp-json\/wp\/v2\/posts\/1398","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/planetozh.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/planetozh.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/planetozh.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/planetozh.com\/blog\/wp-json\/wp\/v2\/comments?post=1398"}],"version-history":[{"count":0,"href":"https:\/\/planetozh.com\/blog\/wp-json\/wp\/v2\/posts\/1398\/revisions"}],"wp:attachment":[{"href":"https:\/\/planetozh.com\/blog\/wp-json\/wp\/v2\/media?parent=1398"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/planetozh.com\/blog\/wp-json\/wp\/v2\/categories?post=1398"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/planetozh.com\/blog\/wp-json\/wp\/v2\/tags?post=1398"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}