README.rdoc in authlogic_rpx-1.0.3 vs README.rdoc in authlogic_rpx-1.0.4

@@ -33,41 +33,41 @@
 
 Three gems are required: authlogic, grosser-rpx_now, and authlogic_rpx. Install these as appropriate to your environment and preferences.
 
 Currently tested versions:
 * authlogic 2.1.2,2.1.1
-* grosser-rpx_now 0.5.10
-* authlogic_rpx 1.0.3
+* rpx_now 0.6.6
+* authlogic_rpx 1.0.4
 
 
 === 1. Direct gem installation
 
   sudo gem install authlogic
-  sudo gem install grosser-rpx_now --source http://gems.github.com
+  sudo gem install rpx_now --source http://gemcutter.org
   sudo gem install authlogic_rpx --source http://gemcutter.org
 
 
 === 2. Using Rails config.gems
 
 Include in config/environment.rb:
   
-  config.gem "authlogic"
-  config.gem "grosser-rpx_now", :lib => "rpx_now", :source => 'http://gems.github.com'
-  config.gem "authlogic_rpx", :source => 'http://gemcutter.org'
+  config.gem 'authlogic', :version => '>= 2.1.1'
+  config.gem 'rpx_now', :version => '>= 0.6.6', :source => 'http://gemcutter.org'
+  config.gem 'authlogic_rpx', :version => '>= 1.0.4', :source => 'http://gemcutter.org'
 
 Then to install, run from the command line:
 
   sudo rake gems:install
 
 
 === 3. Using .gems file (e.g for heroku.com deployments)
 
 Include in RAILS_ROOT/.gems:
   
-  authlogic
-  grosser-rpx_now --source gems.github.com
-  authlogic_rpx --source gemcutter.org
+  authlogic --version '>= 2.1.1'
+  rpx_now --version '>= 0.6.6' --source gemcutter.org
+  authlogic_rpx --version '>= 1.0.4' --source gemcutter.org
 
 
 == Using Authlogic RPX
 
 <i>Note: in what follows, the user model is called User and the session controller takes the name UserSession (the authlogic convention). You are not restricted to these names - could be Member and MemberSession for example - but for simplicity, this documentation will stick to using the "User" convention.</i>
@@ -77,23 +77,25 @@
 An important capability to be aware of is "auto registration". This means that when a user has logged in with RPX, if an account does not already exist in your application, it will be automatically created. That is, there is no separate/special "register" step for users to go through before just signing in. You can disable this if you need, but for most sites that use RPX as a primary authentication mechanism, this is probably what you want to happen.
 
 The main steps for enabling Authlogic RPX: 
 * 1. Enable RPX for your user model
 * 2. Add RPX configuration for the Authlogic session model
-* 3 Add custom user profile mapping (optional)
+* 3. Add custom user profile mapping (optional)
 * 4. Add application controller helpers: current_user, current_user_session
 * 5. Setup the Authlogic session controller
 * 6. Setup the Authlogic user controller
 * 7. Use view helpers to provide login links
 * 8. Allow users to "Add RPX" to existing accounts (optional)
 
 
 === 1. Enable RPX for your user model
 
 The user model requires an additional field called "rpx_identifier". Creat a migration to add this. 
-You may need to remove database constraints on other fields if they will be unused in the RPX case (e.g. crypted_password and password_salt to make password authentication optional)
+You may need to remove database constraints on other fields if they will be unused in the RPX case (e.g. crypted_password and password_salt to make password authentication optional).
 
+If you are using auto-registration, you must also remove any database constraints for fields that will be automatically mapped (see notes in "3. Add custom user profile mapping during auto-registration")
+
   class AddUsersRpxIdentifier < ActiveRecord::Migration
     def self.up
       add_column :users, :rpx_identifier, :string
       add_index :users, :rpx_identifier
 
@@ -154,23 +156,24 @@
   	rpx_extended_info
   end
 
 {See the source for the sample user_session.rb}[http://github.com/tardate/rails-authlogic-rpx-sample/blob/master/app/models/user_session.rb].
 
-=== 3. Add custom user profile mapping during auto-registration (optional)
+=== 3. Add custom user profile mapping (optional)
 
-When users auto-register, profile data from RPX is available to be inserted in the user's record on your site. By default, authlogic_rpx will map the username and email fields.
+Authlogic_rpx provides three hooks for mapping information from the RPX profile into your application's user model:
+  
+* map_rpx_data: user profile mapping during auto-registration
+* map_rpx_data_each_login: user profile mapping during login
+* map_added_rpx_data: user profile mapping when adding RPX to an existing account
+ 
+See https://rpxnow.com/docs#profile_data for the definition of available attributes in the RPX profile.
 
-WARNING: if you are using auto-registration, any fields you map should NOT have unique constraints enforced at the database level.
-Authlogic_rpx will optimistically attempt to save the user record during registration, and violating a unique constraint will cause the authentication/registration to fail.
+=== 3a. map_rpx_data: user profile mapping during auto-registration
 
-You can/should enforce any required validations at the model level e.g.
+When users auto-register, profile data from RPX is available to be inserted in the user's record on your site. By default, authlogic_rpx will map the username and email fields.
 
-  validates_uniqueness_of   :username, :case_sensitive => false
-  
-This will allow the auto-registration to proceed, and the user can be given a chance to rectify the validation errors on your user profile page.
-			
 If you have other fields you want to map, you can provide your own implementation of the map_rpx_data method in the UserSession model. In that method, you will be updating the "self.attempted_record" object, with information from the "@rpx_data" object. See the {RPX documentation}[https://rpxnow.com/docs#profile_data] to find out about the set of information that is available. 
 
   class UserSession < Authlogic::Session::Base
   	rpx_key RPX_API_KEY
   	rpx_extended_info
@@ -194,10 +197,66 @@
     	end
     end
   	
   end
 
+{See the source for the sample user_session.rb}[http://github.com/tardate/rails-authlogic-rpx-sample/blob/master/app/models/user_session.rb].
+
+WARNING: if you are using auto-registration, any fields you map should NOT have constraints enforced at the database level.
+Authlogic_rpx will optimistically attempt to save the user record during registration, and violating a database constraint will cause the authentication/registration to fail.
+
+You can/should enforce any required validations at the model level e.g.
+
+  validates_uniqueness_of   :username, :case_sensitive => false
+  
+This will allow the auto-registration to proceed, and the user can be given a chance to rectify the validation errors on your user profile page.
+
+If it is not acceptable in your application to have user records created with potential validation errors in auto-populated fields, you will need to override map_rpx_data and implement whatever special handling makes sense in your case. For example:
+  
+* directly check for uniqueness and other validation requirements
+* automatically "uniquify" certain fields like username
+* save conflicting profile information to "pending user review" columns or a seperate table
+
+
+==== 3b. map_rpx_data_each_login: user profile mapping during login
+
+map_rpx_data_each_login provides a hook to allow you to map RPX profile information every time the user logs in.
+
+By default, nothing is mapped. If you have other fields you want to map, you can provide your own implementation of the map_rpx_data_each_login method in the UserSession model.
+
+This would mainly be used to update relatively volatile information that you are maintaining in the user model (such as profile image url)
+
+In the map_rpx_data_each_login procedure, you will be writing to fields of the "self.attempted_record" object, pulling data from the @rpx_data object. For example:
+			
+	def map_rpx_data_each_login
+		# we'll always update photo_url
+		self.attempted_record.photo_url = @rpx_data['profile']['photo']
+	end
+
+{See the source for the sample user_session.rb}[http://github.com/tardate/rails-authlogic-rpx-sample/blob/master/app/models/user_session.rb].
+
+
+==== 3c. map_added_rpx_data: user profile mapping when adding RPX to an existing account
+
+map_added_rpx_data maps additional fields from the RPX response into the user object during the "add RPX to existing account" process.
+
+By default, it only maps the rpx_identifier field. If you have other fields you want to map, you can provide your own implementation of the map_added_rpx_data method in the User model (NOT UserSession, unlike for map_rpx_data and map_rpx_data_each_login).
+
+NB: If you override this method, you will be responsible for also mapping the rpx_identifier.
+
+In the map_added_rpx_data procedure, you will be writing to fields of the "self" object, pulling data from the rpx_data parameter. For example:
+
+	def map_added_rpx_data( rpx_data )
+		self.rpx_identifier = rpx_data['profile']['identifier']
+
+		# map some additional fields, e.g. photo_url
+		self.photo_url = rpx_data['profile']['photo'] if photo_url.blank?
+	end
+
+{See the source for the sample user.rb}[http://github.com/tardate/rails-authlogic-rpx-sample/blob/master/app/models/user.rb].
+
+
 === 4. Add application controller helpers: current_user, current_user_session
 
 We'll add current_user and current_user_session helpers. These can then be used in controllers and views to get a handle on the "current" logged in user.
 
   class ApplicationController < ActionController::Base
@@ -365,20 +424,21 @@
 Each takes an options hash:
 * <tt>link_text:</tt> text to use in the link (only used by rpx_popup)
 * <tt>app_name:</tt> name of the application you set when registering your service at rpxnow.com (will be prepended to RPX domain and used in RPX dialogues)
 * <tt>return_url:</tt> url for the RPX callback (e.g. user_sessions_url)
 * <tt>add_rpx:</tt> Optional. If true, requests RPX callback to add to current session. Else runs normal authentication process (default). See "7. Allow users to "Add RPX" to existing accounts"
+* <tt>unobtrusive:</tt> true/false; sets javascript style for link. unobtrusive=true links directly to rpxnow site, whereas unobtrusive=false does a javascript pop-over. Default: true (only used by rpx_popup)
 
 For example, to insert a login link in a navigation bar is as simple as this:
 
 		&lt;div id="user_nav"&gt;
 			&lt;%= link_to "Home", root_path %&gt; |
 			&lt;% if current_user %&gt;
 				&lt;%= link_to "Profile", user_path(:current) %&gt; |
 				&lt;%= link_to "Sign out", signout_path %&gt;
 			&lt;% else %&gt;
-				&lt;%= rpx_popup( :link_text => "Register/Sign in with RPX..", :app_name => "rails-authlogic-rpx-sample", :return_url => user_sessions_url ) %>&gt;
+				&lt;%= rpx_popup( :link_text => "Register/Sign in with RPX..", :app_name => "rails-authlogic-rpx-sample", :return_url => user_sessions_url, :unobtrusive => false ) %>&gt;
 			&lt;% end %&gt;
 		&lt;/div&gt;
 
 === 8. Allow users to "Add RPX" to existing accounts (optional)
 
@@ -405,10 +465,15 @@
 
 You'll note this is almost identical to the "update". The main difference is that it needs to be enabled for :post by RPX. In config/routes.rb:
 
   map.addrpxauth "addrpxauth", :controller => "users", :action => "addrpxauth", :method => :post
 
+To make an "Add RPX authentication for this account.." link, use rpx_popup as for normal RPX login, but set the return_url to the "addrpxauth" callback you have provided, and set the option :add_rpx to tru:
+      
+  &lt;%= rpx_popup( :link_text =&gt; "Add RPX authentication for this account..", :app_name =&gt; RPX_APP_NAME, :return_url =&gt; addrpxauth_url, :add_rpx =&gt; true, :unobtrusive =&gt; false ) %&gt; 
+
+
 === 9. There is no 9
 
 That's all there is. To see Authlogic_RPX in action, check out the demonstration Rails application:
 * <b>Live Demonstration Site:</b> [http://rails-authlogic-rpx-sample.heroku.com]
 * <b>Demonstration site source repository:</b> [http://github.com/tardate/rails-authlogic-rpx-sample]
@@ -449,18 +514,16 @@
 * update gem version refs in README.rdoc
 * update CHANGELOG.rdoc
 
   # update manifest file
   $ rake manifest
-  
   # update gemspec
   $ rake build_gemspec
-  
   # build the gem
   gem build authlogic_rpx.gemspec
-  
   # push the gem to gemcutter (e.g. for version 1.0.3)
   gem push authlogic_rpx-1.0.3.gem
+
 
 == Kudos and Kopywrite
 
 Thanks to {binarylogic}[http://github.com/binarylogic] for cleaning up authentication in rails by creating Authlogic in the first place and offering it to the community.