Twitter API v1.1 OAuth for Enonic CMS

Posted by

Screenshot of the Twitter portlet on http://www.kommunikasjon.no
Screenshot of the Twitter portlet on http://www.kommunikasjon.no

The new Twitter API v1.1 requires OAuth which complicates things for using Twitter features on websites. You can still use widgets to embed user timelines, favorites, lists and search, but custom styling options are minimal. The Enonic Twitter plugin takes care of the authentication so you can focus on the content and presentation of your website. This article explains what the plugin does, what is required to use it, and how to set it up on your site. Code examples are included for showing tweets by hashtag and a list of resource limits.

The Twitter API allows a multitude of operations to interact with users and tweets. Some of these operations require a user context. The operations that do not can be performed with Application-only authentication. Your website can send authenticated requests as an application rather than a logged in user.

Enonic's TwitterAuth function library plugin performs the Twitter Application-only authentication and returns the specified resource as JSON. You can return more than just tweets. For example, you can search in tweets, pull user timelines, retrieve user information, access lists resources, access friends and followers of any account and much more. You won't be able to post tweets or use geo endpoints or anything else that requires a logged in user. A full list of resources that the plugin can retrieve is at the bottom of this article.

The first thing you will need to do is log into https://apps.twitter.com/ and create an app. Fill in the required information. When the app is created, go to the API Keys tab. You will need the API key and API secret for the plugin configuration file. These are also known as the OAuth consumer key and OAuth consumer secret and they are different from the access tokens you would need for user authentication.

The second thing you will need is the plugin itself which you can download here. The .jar file and the twitterAuth.properties file need to be placed in your installation's $CMS_HOME/plugins folder. Edit the properties file to enter your apiKey and apiSecret as shown below. Do not change the name of this file.

That is all the set-up and configuration you need to achieve OAuth connectivity with Twitter. Now the plugin can be used by accessing its execute method in a page-template datasource, which will be explained shortly. You will need a page-template and a menu-item for each Twitter resource that you want to use. All of the page-templates can use the same file, which simply outputs the text JSON of the Twitter resource. 

Below is the entire page-template xsl file:

The page-template datasource must have the name "invokeExtension". The method name is "twitter.execute". The Twitter resource is the value of param1 and the resource parameters go in param2. Don't forget to start your parameter list with a "?" and escape each "&" between parameters. In your Enonic admin console, create a page-template with the xsl file above and the datasource below. Then create a menu-item that uses this page-template.

Page-template datasource for search/tweets.json

The datasource can be made more dynamic with Java el.

Now the JSON for the resource "search/tweets" can be retrieved by an ajax call to the menu-item that uses this page-template. The example below is a portlet xsl file with some html markup and an ajax call to the menu-item that will fill in the markup with tweets. Of course the JavaScript could be in a separate file but I put them together for simplicity.

Here is how it will look with minimal CSS styling. This is where the power of the plugin is apparent because embedded timelines cannot be customized with your own CSS.

 twitter-plutin-search.png

If you only want to show a user timeline and you don't need to customize the look then embedding with a widget is a simpler alternative, as seen below.

Now let us take a look at an example portlet XSL file that will retrieve your app's rate limits for each resource. This is one of many resources that cannot be retrieved with Twitter embedding. First you need to create a menu-item that uses a page-template with the datasource for application/rate_limit_status. Then set the $.getJSON URL to point to that menu-item.

The result of this portlet is a list of resources with the remaining rate limit, as seen below. The rate reset time is included in the JSON and could easily be added to this list. Read more about Twitter rate limits.

twitter-plugin-rates.png

REST API v1.1 resources

The two examples above are just the tip of the iceberg for what can be done with this plugin. Below is the full list of resources that you can use with Twitter's Application-only authentication. However, some of them will require user authentication depending on the parameters supplied.

GET application/rate_limit_status
GET favorites/list
GET followers/ids
GET followers/list
GET friends/list
GET friends/ids
GET friendships/show
GET help/configuration
GET help/languages
GET help/privacy
GET help/tos
GET lists/list
GET lists/members
GET lists/members/show
GET lists/memberships
GET lists/ownerships
GET lists/show
GET lists/statuses
GET lists/subscribers
GET lists/subscribers/show
GET lists/subscriptions
GET search/tweets
GET statuses/oembed
GET statuses/retweeters/ids
GET statuses/retweets/:id
GET statuses/show/:id
GET statuses/user_timeline
GET trends/available
GET trends/closest
GET trends/place
GET users/lookup
GET users/show
GET users/suggestions
GET users/suggestions/:slug
GET users/suggestions/:slug/members

Comments