Friday, January 15, 2010

Twitter Plugin for Open BlueDragon

I finally got a chance to put some time in on a Twitter plugin for Open BlueDragon, and I'm happy to report it's coming along very nicely! The plugin API for OpenBD is really easy to dig into so I thought a Twitter plugin would be as good an exercise as any to get my feet wet. I'm planning a series of blog posts illustrating how to write plugins for OpenBD using the Twitter plugin as an example, so look for that before long.

If you aren't familiar with the plugin API for OpenBD, this is a really slick way for you to add tags and functions to OpenBD that become available natively within your OpenBD instance. The plugin code is written in Java (don't worry, it's not daunting at all), and you then drop a JAR file into your WEB-INF/lib directory. When OpenBD fires up it detects the plugin, registers the functions and tags contained within the plugin, and they're then available for you to use in your CFML code.

You can learn more about the plugin API on the OpenBD wiki, and Alan Williamson also has a great blog post about it. Note that you can do much more than add tags and functions; you can also listen for events occurring inside OpenBD itself and act on these events, and even call CFCs from within your plugin. Very powerful stuff. OpenBD ships with a plugin for IRC, and spreadsheet, wiki, and JavaScript plugins are also implemented via the plugin architecture, and they're available on the OpenBD download page.

But I digress. ;-) The main reason for this post is to give people an overview of how the Twitter plugin is working thus far, but more importantly to ask for your help. Creating a Twitter object with a TwitterNew() function and subsequently calling methods on that was really easy, but of course we CFMLers love our tags, so I also created a CFTWITTER tag. What I don't want to do, however, is add an ACTION attribute to the CFTWITTER tag for every method available on the object, so if people have thoughts on how they'd like the tag to work I'd love some opinions.

So what can you DO with the Twitter plugin for OpenBD? Well, pretty much anything you can do with the Twitter API. Basically I took the excellent jTwitter Java library and rolled that in the OpenBD plugin, and this exposes Twitter functionality natively to CFML. Here's some examples.

<!--- create a new twitter object --->
<cfset myTwitter = TwitterNew('username', 'password') />

<!--- get your friends timeline --->
<cfset timeline = myTwitter.getFriendsTimeline() />

<!--- set your status --->
<cfset status = myTwitter.setStatus("Hello from OpenBD!") />

<!--- search twitter --->
<cfset searchResults ="openbd") />

You get the idea. I've implemented all the methods listed in the jTwitter javadocs, but I'll have documentation for the plugin when I make it available to download. (And hey, if you're a really, really early adopter, email me and I'll send you a copy!)

As for the tags, this is where I need your help. To me it makes complete sense to do this:

<cftwitter action="login"
               variable="myTwitter" />

But the path I don't think is worthwhile to go down is to start implementing a tag action per method available on the Twitter object, since that gets unnecessarily verbose in my opinion. So I started thinking about having some of the more common things you'd want to do with Twitter available via the tag for convenience, and maybe even let the login and action you want to perform be part of the same single tag. So maybe something like this:

<cftwitter action="setStatus"
               status="Hello from OpenBD!" />

<cftwitter action="getFriendsTimeline"
               variable="myTimeline" />

In other words, implement some of the commonly used actions so you can execute these in a single line, but leave the bulk of things available via first instantiating a Twitter object and then calling methods on that. My thinking is if you're going to perform multiple actions it's a lot less verbose to do that with the Twitter object than it is to call a tag each time and pass back in the variable name of the Twitter object on which you want to run the action.

So I'd love to get some opinions on this, and on the idea of a Twitter plugin in general, whether they be good, bad or indifferent.


atomi said...

Would oAuth support be possible in the plugin (I guess not)? I'm using twitter4j currently only because of oAuth.

Todd Rafferty said...

Looks very cool Matt. Unfortunately the predicament you're trying to avoid is what everyone (that uses tags) is used to.

Matthew Woodward said...

Well, yes and no--for example you can't do nearly as many things with the cfspreadsheet and cfimage tags as you can with the related functions, so there's at least precedent for not having the full gamut of functionality available via the tag. And I'm not going to go down the path of adding a top-level function for every action either; using the spreadsheet functions in CF 9 as an example again, in my opinion there should have been a spreadsheet object that you call methods on as opposed to adding 30+ SpreadsheetXXX() functions to which you're continually having to pass the spreadsheet's variable name.

Matthew Woodward said...

Thanks--I hadn't thought about oAuth. Honestly it wouldn't be that difficult to switch to use twitter4j instead of jtwitter for the underlying functionality if oAuth is important to people. I'll do a comparison and see how twitter4j looks.

Matthew Woodward said...

Looked into twitter4j and it's definitely more comprehensive and seems to be more actively maintained than jtwitter, and looks to be only slightly more cumbersome to work with. jtwitter is dead simple but doesn't support everything that twitter4j does, so probably best to make the change now.I'll look into switching this over and keep everyone posted. Thanks for the suggestion!

Matthew Woodward said...

Updated to use twitter4j--loads more functionality, particularly around lists. I haven't tested the list stuff yet but the bulk of it's working great!

Midway Woods Garden said...

Matthew, when will this be ready for others to use?

Matthew Woodward said...

The function-based stuff is pretty much ready to go, I was just struggling with what should and shouldn't be available in tags.I'll review what I have thus far and throw it up in google code so people can grab it and use what's there now. I'll post back here and do another blog post when it's available. Thanks for the prodding! ;-)

Matthew Woodward said...

Source code and JAR file now available, and I'm working on the documentation: