EDIT: plugin now available at Wordpress.org here. Wow that was fast! I gave it a 3 star rating.
Download the plugin here
I’ve been working with WordPress for quite awhile already but I never really read the plugin API for it. So after some stretch of boredom, in between Pugad Baboy and Neal Stephenson, I decided to channel Rachel Ray and “cook up” a wordpress plugin in 30 minutes.
Totally Irrelevant Photo
There are a lot of tutorials showing you how to use the “undocumented API” to embed Yahoo Messenger badges onto your website/blog. I call it undocumented ‘coz I haven’t found the official documentation describing the API (If anyone knows of the official documentation for this, that would be so awesome). So, the said webservice takes your Yahoo!ID as a parameter and returns a gif image which indicates your current presence/status on the messenger service.
The webservice is accessed from the URL: http://opi.yahoo.com/online?u=[username]&m=g&t=1. The u parameter is the yahoo ID you’re requesting status for, the m is for… I don’t know, and the t is for the ‘type’ or which image you want to display. They currently have 24 of these images available. I figured this was a simple enough starting point for our plugin.
These are my goals for the plugin:
- Allow users to add a widget that displayed these Yahoo Badges.
- Allow users to selected custom images for online and offline modes.
- On click, allow viewers to initiate chat or some other action to the displayed badge.
- Have a fun and easy to use settings page.
I started off playing around with the webservice and it yielded some interesting results. Setting the m parameter to a value other than ‘g’ returned ‘01′ for online and ‘00′ for offline. This bit of information allowed me to write a utility class that returned the online status of the user, which we can use for our custom images feature.
Now for the wordpress plugin part. Code first, explain later.
We want to add a widget where we can place our badge. I was impressed with wordpress’ simplicity: you just call register_sidebar_widget([widget_name],[callback]) where callback is the function that displays your wordpress sidebar widget. To display the widget, I’ve created the function ym_status_widget() and used this as the callback to register_sidebar_widget().
But wait! We need to set some options to set on our widget! We can call register_widget_control([widget_name],[callback]) to register a callback function that basically displays the form that will appear under Appearance->Widgets. For this we’ve created the function ym_status_widget_control(). As you can see it’s some simple form processing code that allows us to save the title we want displayed before our widget. I’ve isolated the actual form HTML in a another file, ym_status_control.phtml, for sake of code cleanliness. A lot of plugin writers try to stuff everything in one file, I never understood their motivation for that. What’s interesting to note here is get_option('ym_status'). Plugins and other wordpress values can be stored in it’s database as ‘options’. We are saving our plugin’s state, in an option called ‘ym-status’.
I’ve wrapped this two functions, ym_status_widget() and ym_status_widget_control() in another function, ym_status_widget_init. As you can see, it is again a callback specified to our call to add_action() on the 2nd to the last line. This ensures that this widget is only loaded when a dynamic sidebar is available and widget-ready.
Before continuing with the actual template for the widget itself, I decided to create the admin page that will appear under the Settings menu. This settings area will allow us to: specify the Yahoo!ID we want to track; select custom images, if any, we want display; choose what clicking the widget does; plus, some additional formatting options. Similar to the options page we’ve just created the callback function, ym_status_options that contains form processing code. The form is again isolated in it’s own template file, ym_status_options.
The Admin Menu
As you can see, we allow the user to select images provided by the webservice. Now I could have gone in and saved each of the status images, but a)we have a 30-minute time limit and, b)that wouldn’t be cool. So I decided to download the images using the utility function we just created. This script downloads all 24 images for us, we just have to supply a username, set it online, run the script, set it offline, then run the script again. What a timesaver!
Now that everything is ready we can go and write the actual widget. Let’s look back to ym_status_widget(). It takes some options and arguments, displays some markup, then calls display_ym_status_widget(), which contains the code for displaying the widget. I wrapped that in a function so that anyone can just call display_ym_status_widget() and display it in areas other than the sidebar (a post perhaps). This includes a template, ym_status_widget.phtml, for the actual widget HTML.
This simply takes the options we’ve set under our administration panels and uses those to build the HTML for our widget. This is where we utilize the YmStatus class to check user status and display their selected custom image (if any.)
And that’s it. We’ve built our wordpress plugin in under 30 minutes. I admit it’s a little sloppy, but it does the job! Download the plugin here
