Creating A Useful WordPress Widget, Using Topsy

Yesterday, I was looking for a way to create a Wordpress widget that would use Twitter as a search engine. While there are some awesome Twitter plugins out there, none fully covered my needs. Finally, I run accross Topsy. Topsy is a search engine that finds information from Twitter. It uses it's own search algorithm that sorts tweets based on the author's influence. Topsy defines influence like this:

Topsy Influence measures the likelihood that, each time you say something, people will pay attention. Influence for Twitter users is computed using all historical retweets: millions of real, public statements indicating who’s listening to whom. On our website, roughly the top 0.2% most influential of all Twitter users are tagged “Highly Influential”, and “Influential” tags appear for the top 0.5% most influential Twitter users. So if Topsy says you are influential, you are part of a pretty small group!

Topsy provides plugins for Wordpress, web browsers and bookmarklets but the most useful thing that Topsy provides is it's API. The Otter API provides access to topsy search results, URL information and author information along with the intermediate data (like author influence) that is used in creation of search rankings. Topsy has been created using the Otter API, and almost everything available on the site is accessible to developers. Using Otterapi is plain simple! If you read this helpful resources page, then you will be able of using the API in minutes. Topsy's API helped me create the widget I needed and I would like to share it with you.

The Widget

What I needed was a way to display the recent links posted by a particular Twitter user. The widget went far above that. At the end of this post, the widget will be able to :

• Display Author Links
• Display Author Information
• Display a list of authors talking about something we want
• Display a list of related links about a specific URL
• Search Twitter

You can go on reading to learn how it is done or Download it and use it in your Wordpress.

Creating the Widget: The Skeleton

I used the skeleton provided by Automattic for creating widgets using the Wordpress Widgets API. The skeleton after the changes required for our widget looks like this: [code language="php"]class topsy extends WP_Widget { /** constructor */ function topsy() { parent::WP_Widget(false, $name = 'topsy'); } /** @see WP_Widget::widget */ function widget($args, $instance) { extract( $args ); $title = apply_filters('widget_title', $instance['title']); ?> <?php echo $before_widget; ?> <?php if ( $title ) echo $before_title . $title . $after_title; ?> Hello, World! <?php echo $after_widget; ?> <?php } /** @see WP_Widget::update */ function update($new_instance, $old_instance) { return $new_instance; } /** @see WP_Widget::form */ function form($instance) { $title = esc_attr($instance['title']); ?> <p><label for="<?php echo $this->get_field_id('title'); ?>"><?php _e('Title:'); ?> <input id="<?php echo $this->get_field_id('title'); ?>" name="<?php echo $this->get_field_name('title'); ?>" type="text" value="<?php echo $title; ?>" /></label></p> <?php } }[/code] This is all we need to add our code and create the widget.

Creating the Widget: The Options

Adding options on your widgets is very easy. All you need to do is output the fields needed to update your widget inside the form() method. In our case we need 3 fields:

• The Widget's title
• The Otterapi method to use
• The parameters passed to the API call

The code is: [code lang="php"]function form($instance) { //Defaults $instance = wp_parse_args( (array) $instance, array('title'=>'', 'method'=>'links', 'author'=>'thyclub') ); $title = htmlspecialchars($instance['title']); $method = htmlspecialchars($instance['method']); $author = htmlspecialchars($instance['author']); // Output the options echo '<p style="text-align:right;"><label for="' . $this->get_field_name('title') . '">' . __('Title:') . ' <input style="width: 250px;" id="' . $this->get_field_id('title') . '" name="' . $this->get_field_name('title') . '" type="text" value="' . $title . '" /></label></p>'; // Methods select field echo '<p style="text-align:right;"><label for="' . $this->get_field_name('method') . '">' . __('Topsy Method:') . ' <select style="width: 200px;" id="' . $this->get_field_id('method') . '" name="' . $this->get_field_name('method') . '"><option value="' . $method . '" selected="selected">'. $method .'</option><option value="authorinfo">Author Info</option><option value="authorsearch">Author Search</option><option value="related">Related</option><option value="search">Search</option><option value="links">Author Links</option></select></label></p>'; // Parameters field echo '<p style="text-align:right;"><label for="' . $this->get_field_name('author') . '">' . __('Parameter:') . ' <input style="width: 200px;" id="' . $this->get_field_id('author') . '" name="' . $this->get_field_name('author') . '" type="text" value="' . $author . '" /></label></p>'; }[/code]

Creating the Widget: Otterapi implementation

We need to add a function call where we want our widget to display the results it gets from Topsy. So, we will alter the widget() method so that it calls our function. What the method does, is to switch method cases and call a different API method each time. As you might have noticed, Otterapi's response is JSON but you can choose from XML, JSON or TXT formats also. It is your choice which format you will use and why. I prefer JSON because it is an easy way to parse it. [code lang="php"]function widget($args, $instance) { extract( $args ); $title = apply_filters('widget_title', $instance['title']); ?> <?php echo $before_widget; ?> <?php if ( $title ) echo $before_title . $title . $after_title; ?> //Here we place our call and we pass the $instance var <?php $this->topsy_start($instance); ?> <?php echo $after_widget; ?> <?php }[/code] And we create our topsy_start() method: [code lang="php"]function topsy_start($options){ //decide what to do based on desired method switch($options['method']){ case "links": $url = 'http://otter.topsy.com/linkposts.json?url=http://twitter.com/'.$options['author']; $contents = file_get_contents($url); $contents = json_decode($contents); foreach($contents->response->list as $value){ echo "<li><a href='".$value->target->url."' title='".$value->target->title."'>".$value->target->title."</a></li>"; } break; case "authorinfo": $url = 'http://otter.topsy.com/authorinfo.json?url=http://twitter.com/'.$options['author']; $contents = file_get_contents($url); $contents = json_decode($contents); echo "<li>Twitter Name:<a href='".$contents->response->url."'>".$contents->response->name."</a><br />"; echo "Description:".$contents->response->description."</li>"; break; case "authorsearch": $url = 'http://otter.topsy.com/authorsearch.json?q='.$options['author']; $contents = file_get_contents($url); $contents = json_decode($contents); foreach($contents->response->list as $value){ echo "<li><a href='".$value->url."' title='".$value->name."'>".$value->nick."</a><br />".$value->description."</li>"; } break; case "related": $url = 'http://otter.topsy.com/related.json?url=http://'.$options['author'].'/'; $contents = file_get_contents($url); $contents = json_decode($contents); foreach($contents->response->list as $value){ echo "<li><a href='".$value->url."' title='".$value->title."'>".$value->title."</a><br />Trackbacks: (".$value->trackback_total.")</li>"; } break; case "search": $url = 'http://otter.topsy.com/search.json?q='.$options['author'].'&window=auto'; $contents = file_get_contents($url); $contents = json_decode($contents); foreach($contents->response->list as $value){ echo "<li><a href='".$value->url."' title='".$value->title."'>".$value->title."</a><br />Trackbacks: (".$value->trackback_total.")<br />Hits:(".$value->hits.")<br />Score:(".$value->score.")</li>"; } break; } }[/code]

Creating the Widget: As a Plugin

In order for Wordpress to recognize our widget, we need to place some headers in our file so that we will be able to install it, activate and deactivate it as we would with any other plugin. You can then use it as plugin or you can even drop it into : WORDPRESS_DIR/plugins/widgets/ and it will work again. The code needed is : [code lang="php"]/* * Plugin Name: Topsy Search Widget * Version: 1.0 * Plugin URI: http://jeez.eu/2009/12/02/creating-a-useful-wordpress-widget-using-topsy/ * Description: This will create a widget that you can use to display various Twitter search results using <a href="http://topsy.com">Topsy</a>. * Author: Kerasiotis Vasileios * Author URI: http://jeez.eu/ */[/code] and we must place the code at the beginning of our file, just beneath the starting PHP tag. One more thing that we need to do is register our widget. 4 lines of code is enough and we place this code outside our widget class: [code lang="php"]function topsy() { register_widget('topsy'); } add_action('widgets_init', 'topsy');[/code]

Spice it Up

At the moment, our widget is working as we expect it to but how can we tell the user viewing it what it actually does? The visitor will just see a static title that we should change each time we choose another API method. I never liked being forced to change static text each time I decide to change something else. I would like to have the widget understand what it does and, to display a title based on the method used. This is a personal opinion about this widget and you can skip this step. This is how to do it: [code lang="php"]function widget($args, $instance) { extract( $args ); //we can change the title to a more related title switch($instance['method']){ case "links": $title = apply_filters('widget_title', $instance['title'].": Links posted by ".$instance['author']); break; case "authorinfo": $title = apply_filters('widget_title', $instance['title'].": Information about ".$instance['author']); break; case "authorsearch": $title = apply_filters('widget_title', $instance['title'].": People talking about ".$instance['author']); break; case "related": $title = apply_filters('widget_title', $instance['title'].": Related Tweets for ".$instance['author']); break; case "search": $title = apply_filters('widget_title', $instance['title'].": Search Results for ".$instance['author']); break; } ?> <?php echo $before_widget; ?> <?php if ( $title ) echo $before_title . $title . $after_title; ?> <ul> <?php $this->topsy_start($instance); ?> </ul> <?php echo $after_widget; ?> <?php }[/code]

Finished Widget Code

This is the finnished widget code: [code lang="php"]<?php /* * Plugin Name: Topsy Search Widget * Version: 1.0 * Plugin URI: http://jeez.eu/2009/12/02/creating-a-useful-wordpress-widget-using-topsy/ * Description: This will create a widget that you can use to display various Twitter search results using <a href="http://topsy.com">Topsy</a>. * Author: Kerasiotis Vasileios * Author URI: http://jeez.eu/ */ class topsy extends WP_Widget { /** constructor */ function topsy() { parent::WP_Widget(false, $name = 'topsy'); } /** @see WP_Widget::widget */ function widget($args, $instance) { extract( $args ); //we can change the title to a more related title switch($instance['method']){ case "links": $title = apply_filters('widget_title', $instance['title'].": Links posted by ".$instance['author']); break; case "authorinfo": $title = apply_filters('widget_title', $instance['title'].": Information about ".$instance['author']); break; case "authorsearch": $title = apply_filters('widget_title', $instance['title'].": People talking about ".$instance['author']); break; case "related": $title = apply_filters('widget_title', $instance['title'].": Related Tweets for ".$instance['author']); break; case "search": $title = apply_filters('widget_title', $instance['title'].": Search Results for ".$instance['author']); break; } ?> <?php echo $before_widget; ?> <?php if ( $title ) echo $before_title . $title . $after_title; ?> <ul> <?php $this->topsy_start($instance); ?> </ul> <?php echo $after_widget; ?> <?php } function topsy_start($options){ switch($options['method']){ case "links": $url = 'http://otter.topsy.com/linkposts.json?url=http://twitter.com/'.$options['author']; $contents = file_get_contents($url); $contents = json_decode($contents); foreach($contents->response->list as $value){ echo "<li><a href='".$value->target->url."' title='".$value->target->title."'>".$value->target->title."</a></li>"; } break; case "authorinfo": $url = 'http://otter.topsy.com/authorinfo.json?url=http://twitter.com/'.$options['author']; $contents = file_get_contents($url); $contents = json_decode($contents); echo "<li>Twitter Name:<a href='".$contents->response->url."'>".$contents->response->name."</a><br />"; echo "Description:".$contents->response->description."</li>"; break; case "authorsearch": $url = 'http://otter.topsy.com/authorsearch.json?q='.$options['author']; $contents = file_get_contents($url); $contents = json_decode($contents); foreach($contents->response->list as $value){ echo "<li><a href='".$value->url."' title='".$value->name."'>".$value->nick."</a><br />".$value->description."</li>"; } break; case "related": $url = 'http://otter.topsy.com/related.json?url=http://'.$options['author'].'/'; $contents = file_get_contents($url); $contents = json_decode($contents); foreach($contents->response->list as $value){ echo "<li><a href='".$value->url."' title='".$value->title."'>".$value->title."</a><br />Trackbacks: (".$value->trackback_total.")</li>"; } break; case "search": $url = 'http://otter.topsy.com/search.json?q='.$options['author'].'&window=auto'; $contents = file_get_contents($url); $contents = json_decode($contents); foreach($contents->response->list as $value){ echo "<li><a href='".$value->url."' title='".$value->title."'>".$value->title."</a><br />Trackbacks: (".$value->trackback_total.")<br />Hits:(".$value->hits.")<br />Score:(".$value->score.")</li>"; } break; } } /** @see WP_Widget::update */ function update($new_instance, $old_instance) { return $new_instance; } /** @see WP_Widget::form */ function form($instance) { //Defaults $instance = wp_parse_args( (array) $instance, array('title'=>'', 'method'=>'links', 'author'=>'thyclub') ); $title = htmlspecialchars($instance['title']); $method = htmlspecialchars($instance['method']); $author = htmlspecialchars($instance['author']); # Output the options echo '<p style="text-align:right;"><label for="' . $this->get_field_name('title') . '">' . __('Title:') . ' <input style="width: 250px;" id="' . $this->get_field_id('title') . '" name="' . $this->get_field_name('title') . '" type="text" value="' . $title . '" /></label></p>'; # Methods select field echo '<p style="text-align:right;"><label for="' . $this->get_field_name('method') . '">' . __('Topsy Method:') . ' <select style="width: 200px;" id="' . $this->get_field_id('method') . '" name="' . $this->get_field_name('method') . '"><option value="' . $method . '" selected="selected">'. $method .'</option><option value="authorinfo">Author Info</option><option value="authorsearch">Author Search</option><option value="related">Related</option><option value="search">Search</option><option value="links">Author Links</option></select></label></p>'; # Parameters field echo '<p style="text-align:right;"><label for="' . $this->get_field_name('author') . '">' . __('Parameter:') . ' <input style="width: 200px;" id="' . $this->get_field_id('author') . '" name="' . $this->get_field_name('author') . '" type="text" value="' . $author . '" /></label></p>'; } } /** * Register Topsy widget. * * Calls 'widgets_init' action after the Topsy widget has been registered. */ function topsy() { register_widget('topsy'); } add_action('widgets_init', 'topsy'); ?>[/code] Get the plugin here.