Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 167 lines (99 sloc) 5.574 kb
279e336 Paul Gallagher initial working example
authored
1 = RAILS-TWITTER-OAUTH-SAMPLE
2
bf360e3 Paul Gallagher cleaned up readme formatting so it's sort of minimal rdoc safe
authored
3 * Prepared by: paul gallagher - http://tardate.com
4 * Repository: http://github.com/tardate/rails-twitter-oauth-sample/tree/master
5 * Demonstration site: http://rails-twitter-oauth-sample.heroku.com
6 * Related blog post: http://tardate.blogspot.com/2009/06/using-twitter-oauth-with-rails-sample.html
279e336 Paul Gallagher initial working example
authored
7
8 == Purpose
9
6dc8c7b Paul Gallagher cleaned up some documentation
authored
10 Demonstrates the use of rails with the Twitter RESTful API with OAuth 1.0a.
279e336 Paul Gallagher initial working example
authored
11 Uses the oauth ruby gem.
12
970d007 Paul Gallagher added version and changelog notice for 1.0.2
authored
13 == Version and change log
14
bf360e3 Paul Gallagher cleaned up readme formatting so it's sort of minimal rdoc safe
authored
15 * 1.0.2 - updated to fix oauth 0.4.0 compatibility issue
16 * 1.0.1 - update to new pagination mechanism for social graph methods
17 * 1.0 - initial release
279e336 Paul Gallagher initial working example
authored
18
19 == Other References
20
21 1. Twitter API documentation - http://apiwiki.twitter.com/
22 2. OAuth gem http://github.com/pelle/oauth/tree/master
23 3. Twitter OAuth gem (another REST API client library for Ruby - not used in this example) http://github.com/moomerman/twitter_oauth/tree/master
24
25
26 == Required gems
27
28 These need to be installed in addition to all standard gems required by rails:
29
bf360e3 Paul Gallagher cleaned up readme formatting so it's sort of minimal rdoc safe
authored
30 * json (1.1.6 at time of writing)
31 * oauth (0.4.0, 0.3.6, or 0.3.5 at time of writing)
279e336 Paul Gallagher initial working example
authored
32
33 NB: for heroku deployment, these are specified in the .gems file in the root of the project
34
35
36 = STEP-BY-STEP (how the app was created)
37
cee4254 Paul Gallagher updated documentation to clarify API key usage and local testing
authored
38 == 1. Install oauth gem
279e336 Paul Gallagher initial working example
authored
39
40 gem install oauth
9942f61 Paul Gallagher update for oauth 0.4.0 gem
authored
41
42 or
43
44 rake gems:install
279e336 Paul Gallagher initial working example
authored
45
cee4254 Paul Gallagher updated documentation to clarify API key usage and local testing
authored
46 == 2. create the application shell
279e336 Paul Gallagher initial working example
authored
47
48 rails rails-twitter-oauth-sample
49 cd rails-twitter-oauth-sample
50 rake db:create
51
cee4254 Paul Gallagher updated documentation to clarify API key usage and local testing
authored
52 == 3. create a member scaffold
279e336 Paul Gallagher initial working example
authored
53
54 ruby script/generate scaffold member twitter_id:integer screen_name:string token:string secret:string profile_image_url:string
55
6dc8c7b Paul Gallagher cleaned up some documentation
authored
56 Member model updated to use screen_name as the key:
57
bf360e3 Paul Gallagher cleaned up readme formatting so it's sort of minimal rdoc safe
authored
58 def to_param
59 screen_name
60 end
279e336 Paul Gallagher initial working example
authored
61
cee4254 Paul Gallagher updated documentation to clarify API key usage and local testing
authored
62 == 4. Prepare the database
279e336 Paul Gallagher initial working example
authored
63
64 rake db:migrate
65
cee4254 Paul Gallagher updated documentation to clarify API key usage and local testing
authored
66 == 5. Create the oauth support in ./lib
279e336 Paul Gallagher initial working example
authored
67
6dc8c7b Paul Gallagher cleaned up some documentation
authored
68 twitter_oauth.rb
69
5441bcf Paul Gallagher added more detail to aPI key registration requirements
authored
70 * Implements TwitterOauth class, which is a wrapper around the oauth gem, providing specific support for twitter.
71 * As a design principle, the TwitterOauth class logs and re-raises any errors that occur; some custom error classes are defined to suit.
6dc8c7b Paul Gallagher cleaned up some documentation
authored
72 * It includes implementations for many of the twitter api methods (but not all at this point)
279e336 Paul Gallagher initial working example
authored
73
6dc8c7b Paul Gallagher cleaned up some documentation
authored
74 oauth_system.rb
75
76 * A controller mixin module to provide twitter oauth support in an application.
77 * Uses the TwitterOauth class for oauth functionality.
78 * Works specifically with the Member ActiveRecord class to update/verify user details.
79 * It includes wrappers for many of the twitter api methods, basically to reroute errors into the flash hash.
279e336 Paul Gallagher initial working example
authored
80
81
cee4254 Paul Gallagher updated documentation to clarify API key usage and local testing
authored
82 == 6. Modify MembersController to use OAuth
279e336 Paul Gallagher initial working example
authored
83
84 # include the oauth_system mixin
85 include OauthSystem
86 # specify oauth to be on all user-specific actions
87 before_filter :oauth_login_required, :except => [ :callback, :signout, :index ]
88
cee4254 Paul Gallagher updated documentation to clarify API key usage and local testing
authored
89 == 7. Specify routes
279e336 Paul Gallagher initial working example
authored
90
6dc8c7b Paul Gallagher cleaned up some documentation
authored
91 Map members resources
92 Hook /members/callback method to module OauthSystem.callback
279e336 Paul Gallagher initial working example
authored
93
6dc8c7b Paul Gallagher cleaned up some documentation
authored
94 map.resources :members,
95 :collection => { :callback => :get }
279e336 Paul Gallagher initial working example
authored
96
6dc8c7b Paul Gallagher cleaned up some documentation
authored
97 Hook /signout method to module OauthSystem.signout:
279e336 Paul Gallagher initial working example
authored
98
6dc8c7b Paul Gallagher cleaned up some documentation
authored
99 map.signout '/signout', :controller => 'members', :action => 'signout'
279e336 Paul Gallagher initial working example
authored
100
6dc8c7b Paul Gallagher cleaned up some documentation
authored
101 For the sample app, use MembersController.index as the landing page:
279e336 Paul Gallagher initial working example
authored
102
6dc8c7b Paul Gallagher cleaned up some documentation
authored
103 map.root :controller => "members"
279e336 Paul Gallagher initial working example
authored
104
105
cee4254 Paul Gallagher updated documentation to clarify API key usage and local testing
authored
106 == 8. Customise views and controller methods for some basic functionality
279e336 Paul Gallagher initial working example
authored
107
6dc8c7b Paul Gallagher cleaned up some documentation
authored
108 MembersController actions
109
110 * index - a basic landing page
111 * show - main page for logged-in user
112 * partialfriends - xhr responder to render friends list
113 * partialfollowers - xhr responder to render followers list
114 * partialmentions - xhr responder to render mentions list
115 * partialdms - xhr responder to render direct messages list
279e336 Paul Gallagher initial working example
authored
116
117
cee4254 Paul Gallagher updated documentation to clarify API key usage and local testing
authored
118 == 9. Add rake task to demonstrate proxy-login
279e336 Paul Gallagher initial working example
authored
119
6dc8c7b Paul Gallagher cleaned up some documentation
authored
120 See lib/tasks/test.rake:
121 demo_proxy_login task connects as the last member and exercises the API a bit
122
123 To execute:
124
125 rake demo_proxy_login
279e336 Paul Gallagher initial working example
authored
126
cee4254 Paul Gallagher updated documentation to clarify API key usage and local testing
authored
127 == 10. Configuring twitter application keys
58c5e41 Paul Gallagher update doc to cover env usage
authored
128
129 Register your application at http://twitter.com/oauth_clients
130
5441bcf Paul Gallagher added more detail to aPI key registration requirements
authored
131 Be sure to select the following settings in the registration:
132 * Application Type = Browser
133 * Callback URL = the fully qualified callback to your app e.g. http://rails-twitter-oauth-sample.heroku.com/members/callback
134 * Default Access type = Read & Write (if you want to be able to do things like post status updates)
135 * Use Twitter for login = yes
136
cee4254 Paul Gallagher updated documentation to clarify API key usage and local testing
authored
137 Note the "application key" and "consumer secret" numbers that twitter generates - these are unique for your application
138 and are required to complete the configuration.
139
140 Add the twitter application key and consumer secret as operating system environment variables
141 (TWOAUTH_KEY and TWOAUTH_SECRET respectively).
142
ec95520 Paul Gallagher changed callback url to be an environment setting
authored
143 Set your callback URL as operating system environment variable (TWOAUTH_CALLBACK).
144
cee4254 Paul Gallagher updated documentation to clarify API key usage and local testing
authored
145 Alternatively, you can edit config/environment.rb to set these directly.
58c5e41 Paul Gallagher update doc to cover env usage
authored
146
cee4254 Paul Gallagher updated documentation to clarify API key usage and local testing
authored
147 If you are using heroku, add the environment keys using the heroky utility (gem):
58c5e41 Paul Gallagher update doc to cover env usage
authored
148
ec95520 Paul Gallagher changed callback url to be an environment setting
authored
149 heroku config:add TWOAUTH_KEY=8N029N81 TWOAUTH_SECRET=9s83109d3+583493190 TWOAUTH_CALLBACK=http://rails-twitter-oauth-sample.heroku.com/members/callback
150
279e336 Paul Gallagher initial working example
authored
151
cee4254 Paul Gallagher updated documentation to clarify API key usage and local testing
authored
152 == 11. Testing the application locally
279e336 Paul Gallagher initial working example
authored
153
cee4254 Paul Gallagher updated documentation to clarify API key usage and local testing
authored
154 When you register the application at twitter, you will specify a fully qualified callback URL
155 e.g. http://rails-twitter-oauth-sample.heroku.com/members/callback
279e336 Paul Gallagher initial working example
authored
156
cee4254 Paul Gallagher updated documentation to clarify API key usage and local testing
authored
157 This is the address that twitter sends users back to after the twitter authentication step.
279e336 Paul Gallagher initial working example
authored
158
ec95520 Paul Gallagher changed callback url to be an environment setting
authored
159 To test on a local development machine (not known on the web/in DNS as the domain name in the callback),
cee4254 Paul Gallagher updated documentation to clarify API key usage and local testing
authored
160 you can simply add the registered domain to your hosts file (aliasing localhost) e.g.
279e336 Paul Gallagher initial working example
authored
161
cee4254 Paul Gallagher updated documentation to clarify API key usage and local testing
authored
162 127.0.0.1 rails-twitter-oauth-sample.heroku.com
279e336 Paul Gallagher initial working example
authored
163
cee4254 Paul Gallagher updated documentation to clarify API key usage and local testing
authored
164 NB: most browsers will need to be restarted each time you change this,
165 as the resolved name will have been cached if you have already used the address.
279e336 Paul Gallagher initial working example
authored
166
Something went wrong with that request. Please try again.