This morning I pushed out the latest release of monkehTweet, the open-source ColdFusion wrapper to interact with the Twitter API.
There are a number of revisions, enhancements and changes to the code and the service layer.
Firstly, and very important for anyone using the older versions of the package – I went through the Twitter documentation to check and update all available methods and add additional / new parameters to the code. Whilst doing so, I changed some of the argument names to fall in line with the official Twitter names to make it easier for me to maintain and update future releases.
As a result, PLEASE make sure you check your use of parameter names in any methods you are calling with the actual names of the arguments available to avoid any possibility of disruption or errors. Only a few methods have had some arguments changed this way, but I’d still recommend just checking your code to make sure. As said, this will greatly improve future update times and revisions.
Update with Media
The biggest addition to the project is probably the inclusion of the new update_with_media function from Twitter, which allows you to post one image (either a gif, jpeg or png) with the status update. This took some considerable thinking, plenty of coffee and a little refactoring of code to put in to place, but it’s finally there.
In terms of use, it’s incredibly simple. The two required parameters are the status and the media file to upload and include alongside the status. The media file itself is the full path of the file on the server.
Let’s have a look at the example below:
objMonkehTweet = new com.coldfumonkeh.monkehTweet( consumerKey = '< your consumer key >', consumerSecret = '< your consumer secret >', oauthToken = '< your oauth token >', oauthTokenSecret = '< your oauth token secret >', userAccountName = '< your account name >' ); objMonkehTweet.postUpdate( status="@iotashan - the new release has something you've been waiting for.. yes, the longest 24 hours in the world, ever, is finally over!", in_reply_to_status_id='134657766970228736' );
Here we have a simple status update, in reply to a particular status from a follower.
The actual status generated from this call be seen here: http://twitter.com/#!/coldfumonkeh/statuses/138930784303194112
The update_with_media function (or postUpdateWithMedia as it’s called in monkehTweet) is incredibly similar.
objMonkehTweet = new com.coldfumonkeh.monkehTweet( consumerKey = '< your consumer key >', consumerSecret = '< your consumer secret >', oauthToken = '< your oauth token >', oauthTokenSecret = '< your oauth token secret >', userAccountName = '< your account name >' ); // Include the media parameter (full path to file) objMonkehTweet.postUpdateWithMedia( status='@refyner FYI the new ##monkehTweet release has some minor changes to some argument names. ##ColdFusion', media="/Applications/ColdFusion9/wwwroot/monkehTweet/test/code.png", in_reply_to_status_id='135070647205380096' );
The status generated from this call with the attached media file can be seen here: http://twitter.com/coldfumonkeh/statuses/138945147168763904
The single media argument points to the full path of the image file on the server. monkehTweet handles the full upload and authentication procedure in much the same way as it does with every other request through the API.
Under the hood quite a lot more is happening that the user is not aware of. The postUpdateWithMedia method needs to handle the OAuth authentication and header generation slightly differently to all of the other requests within the API. The call to this method is handled through a POST request that needs to go through a multipart/form-data submission, sending the image file in binary, as well as any of the other arguments (status is a required field, so will always be sent in the request).
As the request was being sent in this manner, the OAuth signature needed to be redefined for this method only to just include the oauth_* specific parameters. This was the biggest headache to refactor, but once it was working was incredibly easy.
At present, Twitter only accepts JPG, GIF and PNG files for upload. To assist in ensuring the correct file type has been submitted, the monkehTweet package will check the mimetype of the supplied file, and will only proceed if it matches one of the approved file types. This has been included thanks to the open source project http://magicmime.riaforge.org/ from Paul Connell.
One think to note is that the link generated by Twitter to the upload media file forms part of the 140 character limitation on the overall status. To quote the official documentation for this method:
The Tweet text will be rewritten to include the media URL(s), which will reduce the number of characters allowed in the Tweet text. If the URL(s) cannot be appended without text truncation, the tweet will be rejected and this method will return an HTTP 403 error.
So, if uploading an image, keep an eye on the length of the text within the status to ensure you don’t go over the limit.
Help is at hand
Some more inclusions into this release are the three help methods from Twitter:
- test
- configuration
- languages
Test simply runs a basic call to the API to return a response – very useful for determining the current system status. Languages will provide you with details of the ISO language references that you can then use in certain calls.
The configuration function is incredibly useful for the media uploads. The returned data contains information on the maximum number of media allowed per upload (currently set to one), the size limit of the uploaded image file (very useful to determine if an image SHOULD be uploaded by checking the size), as well as photo size dimensions, URL length as well as some other information.
Grab a copy!
The updated version (v1.3.0) of monkehTweet is available now to download from monkehtweet.riaforge.org or from the github repository here: https://github.com/coldfumonkeh/monkehTweets.
8 Comments on "monkehTweet release and Twitter update_with_media enhancements"
Hi Matt,
Well done and thanks for the media update, I wanted to bring it to your notice, when I read the time line for the user (not profile) I get almost all the tweets from my time line (which I can see in twitter), the only issue is, I don’t see the retweets of the persons I follow when I use your Library to read the tweets of my time line
Hi Philip
have a look at the include_entities and exclude_replies arguments in the method call (included in the latest version – v1.3.0). The include_entities argument should certainly display the details of mentions for each status.
Outstanding! I have a real use for the update_with_media function so I’ll begin testing later today or tomorrow.
Thanks once again for this package, Matt. It makes my life a lot easier, that’s for sure.
Hey Craig! I hope it’s useful to you, my man!
Before I dig into this I thought I’d ask if it can do what I’m after. I want to add a “Log In Using Twitter” feature in my comments system so they can user their Twitter credentials if they don’t want to register for a username on my site. If so, can you identify which methods to use? Thanks much for writing this.
Hi Steve
The current release of monkehTweet doesnt support this. However, I am adding these methods and functionality into the next release of the project, which I hope to push out live within the next week.
I was looking for a twitter api for a site that doesn’t accept php. Is there any restrictions on your library’s use?
Hi Michelle
There are no restrictions in terms of use or license for monkehTweet. Of course anything from my Amazon wishlist would be a nice ‘payment’, but that’s at the user’s discretion.
I hope you enjoy it and it helps out with your project. If you need any help, please let me know.
Many thanks