= RAILS-TWITTER-OAUTH-SAMPLE

Prepared by: paul gallagher - http://tardate.com Repository: http://github.com/tardate/rails-twitter-oauth-sample/tree/master Demonstration site: http://rails-twitter-oauth-sample.heroku.com Related blog post: http://tardate.blogspot.com/2009/06/using-twitter-oauth-with-rails-sample.html

== Purpose

Demonstrates the use of rails with the Twitter RESTful API with OAuth 1.0a. Uses the oauth ruby gem.

== Other References

1. Twitter API documentation - http://apiwiki.twitter.com/
2. OAuth gem http://github.com/pelle/oauth/tree/master
3. Twitter OAuth gem (another REST API client library for Ruby - not used in this example) http://github.com/moomerman/twitter_oauth/tree/master

== Required gems

These need to be installed in addition to all standard gems required by rails:

json (1.1.6 at time of writing) oauth (0.3.5 at time of writing)

NB: for heroku deployment, these are specified in the .gems file in the root of the project

= STEP-BY-STEP (how the app was created)

== 1. Install oauth gem

gem install oauth

== 2. create the application shell

rails rails-twitter-oauth-sample
cd rails-twitter-oauth-sample
rake db:create

== 3. create a member scaffold

ruby script/generate scaffold member twitter_id:integer screen_name:string token:string secret:string profile_image_url:string

Member model updated to use screen_name as the key:

    def to_param
        screen_name
    end

== 4. Prepare the database

rake db:migrate

== 5. Create the oauth support in ./lib

twitter_oauth.rb

• Implements TwitterOauth class, which is a wrapper around the oauth gem, providing specific support for twitter.
• As a design principle, the TwitterOauth class logs and re-raises any errors that occur; some custom error classes are defined to suit.
• It includes implementations for many of the twitter api methods (but not all at this point)

oauth_system.rb

• A controller mixin module to provide twitter oauth support in an application.
• Uses the TwitterOauth class for oauth functionality.
• Works specifically with the Member ActiveRecord class to update/verify user details.
• It includes wrappers for many of the twitter api methods, basically to reroute errors into the flash hash.

== 6. Modify MembersController to use OAuth

# include the oauth_system mixin
include OauthSystem
# specify oauth to be on all user-specific actions
before_filter :oauth_login_required, :except => [ :callback, :signout, :index ]

== 7. Specify routes

Map members resources Hook /members/callback method to module OauthSystem.callback

map.resources :members,
  :collection => { :callback => :get }

Hook /signout method to module OauthSystem.signout:

map.signout '/signout', :controller => 'members', :action => 'signout'

For the sample app, use MembersController.index as the landing page:

map.root      :controller => "members"

== 8. Customise views and controller methods for some basic functionality

MembersController actions

• index - a basic landing page
• show - main page for logged-in user
• partialfriends - xhr responder to render friends list
• partialfollowers - xhr responder to render followers list
• partialmentions - xhr responder to render mentions list
• partialdms - xhr responder to render direct messages list

== 9. Add rake task to demonstrate proxy-login

See lib/tasks/test.rake: demo_proxy_login task connects as the last member and exercises the API a bit

To execute:

rake demo_proxy_login

== 10. Configuring twitter application keys

Register your application at http://twitter.com/oauth_clients

Be sure to select the following settings in the registration:

• Application Type = Browser
• Callback URL = the fully qualified callback to your app e.g. http://rails-twitter-oauth-sample.heroku.com/members/callback
• Default Access type = Read & Write (if you want to be able to do things like post status updates)
• Use Twitter for login = yes

Note the "application key" and "consumer secret" numbers that twitter generates - these are unique for your application and are required to complete the configuration.

Add the twitter application key and consumer secret as operating system environment variables (TWOAUTH_KEY and TWOAUTH_SECRET respectively).

Set your callback URL as operating system environment variable (TWOAUTH_CALLBACK).

Alternatively, you can edit config/environment.rb to set these directly.

If you are using heroku, add the environment keys using the heroky utility (gem):

heroku config:add TWOAUTH_KEY=8N029N81 TWOAUTH_SECRET=9s83109d3+583493190 TWOAUTH_CALLBACK=http://rails-twitter-oauth-sample.heroku.com/members/callback

== 11. Testing the application locally

When you register the application at twitter, you will specify a fully qualified callback URL e.g. http://rails-twitter-oauth-sample.heroku.com/members/callback

This is the address that twitter sends users back to after the twitter authentication step.

To test on a local development machine (not known on the web/in DNS as the domain name in the callback), you can simply add the registered domain to your hosts file (aliasing localhost) e.g.

127.0.0.1       rails-twitter-oauth-sample.heroku.com

NB: most browsers will need to be restarted each time you change this, as the resolved name will have been cached if you have already used the address.