update README in preparation for 1.0. allow passing of display via option

README.md

@@ -2,26 +2,95 @@
 
 This gem contains the Facebook strategy for OmniAuth 1.0.
 
+Supports the OAuth 2.0 server-side flow. Read the Facebook docs for more details: http://developers.facebook.com/docs/authentication
+
 ## Installing
 
 Add to your `Gemfile`:
 
 ```ruby
-gem 'omniauth-facebook', '~> 1.0.0.rc1'
+gem 'omniauth-facebook'
 ```
 
 Then `bundle install`.
 
-## Supported Flows
+## Usage
 
-Supports the Server-side Flow as described in the the Facebook docs:
-http://developers.facebook.com/docs/authentication
+`OmniAuth::Strategies::Facebook` is simply a Rack middleware. Read the OmniAuth 1.0 docs for detailed instructions: https://github.com/intridea/omniauth.
 
-**Pending:** Supports the Client-side Flow via parsing out the verification code from the signed request cookie.
+Here's a quick example, adding the middleware to a Rails app in `config/initializers/omniauth.rb`:
 
-## Ruby
+```ruby
+Rails.application.config.middleware.use OmniAuth::Builder do
+  provider :facebook, ENV['FACEBOOK_KEY'], ENV['FACEBOOK_SECRET'], :scope => 'email', :display => 'popup'
+end
+```
 
-Tested with the following Ruby versions:
+## Configuring
+
+You can configure several options, which you pass in to the `provider` method via a `Hash`:
+
+* `scope`: A comma-separated list of permissions you want to request from the user. See the Facebook docs for a full list of available permissions: http://developers.facebook.com/docs/reference/api/permissions. Default: `email,offline_access`
+* `display`: The display context to show the authentication page. Options are: `page`, `popup`, `iframe`, `touch` and `wap`. Read the Facebook docs for more details: http://developers.facebook.com/docs/reference/dialogs#display. Default: `page`
+
+For example, to request `email`, `offline_access` and `read_stream` permissions and display the authentication page in a popup window:
+ 
+```ruby
+Rails.application.config.middleware.use OmniAuth::Builder do
+  provider :facebook, ENV['FACEBOOK_KEY'], ENV['FACEBOOK_SECRET'], :scope => 'email,offline_access,read_stream', :display => 'popup'
+end
+```
+
+*NB.* If you want to set the `display` format on a per-request basis, you can just pass it to the OmniAuth request phase URL, for example: `/auth/facebook?display=popup`.
+
+## Authentication Hash
+
+Here's an example *Authentication Hash* available in `request.env['omniauth.auth']`:
+
+```ruby
+{
+  :provider => 'facebook',
+  :uid => '1234567',
+  :info => {
+    :nickname => 'jbloggs',
+    :email => 'joe@bloggs.com',
+    :name => 'Joe Bloggs',
+    :first_name => 'Joe',
+    :last_name => 'Bloggs',
+    :image => 'http://graph.facebook.com/1234567/picture?type=square',
+    :urls => { :Facebook => 'http://www.facebook.com/jbloggs' },
+    :location => 'Palo Alto, California'
+  },
+  :credentials => {
+    :token => 'ABCDEF...',
+    :expires_at => 1321747205, # when the access token expires
+    :expires => true # if you request `offline_access` this will be false
+  },
+  :extra => {
+    :raw_info => {
+      :id => '1234567',
+      :name => 'Joe Bloggs',
+      :first_name => 'Joe',
+      :last_name => 'Bloggs',
+      :link => 'http://www.facebook.com/jbloggs',
+      :username => 'jbloggs',
+      :location => { :id => '123456789', :name => 'Palo Alto, California' },
+      :gender => 'male',
+      :email => 'joe@bloggs.com',
+      :timezone => -8,
+      :locale => 'en_US',
+      :verified => true,
+      :updated_time => '2011-11-11T06:21:03+0000'
+    }
+  }
+}
+```
+
+The precise information available may depend on the permissions which you request.
+
+## Supported Rubies
+
+Actively tested with the following Ruby versions:
 
 - MRI 1.9.3
 - MRI 1.9.2

example/config.ru

@@ -21,7 +21,7 @@ end
 use Rack::Session::Cookie
 
 use OmniAuth::Builder do
-  provider :facebook, ENV['APP_ID'], ENV['APP_SECRET'], :scope => 'email,read_stream', :authorize_params => { :display => 'popup' }
+  provider :facebook, ENV['APP_ID'], ENV['APP_SECRET'], :scope => 'email,read_stream', :display => 'popup'
 end
 
 run App.new

lib/omniauth/strategies/facebook.rb

@@ -19,6 +19,8 @@ module OmniAuth
         :param_name => 'access_token'
       }
       
+      option :authorize_options, [:scope, :display]
+      
       uid { raw_info['id'] }
       
       info do