README.rdoc in authpds-0.0.19 vs README.rdoc in authpds-0.0.20

@@ -1,29 +1,74 @@
 = Authpds
 
-This project provides a mechanism for authenticating via Ex Libris' Patron Directory Services (PDS) and provides hooks for making authorization decisions based on the user information provided by PDS.  It leverages the authlogic gem and depends on a User-like model.
+This gem provides a mechanism for authenticating via Ex Libris' Patron Directory Services (PDS) and provides hooks for making authorization decisions based on the user information provided by PDS.  It leverages the authlogic gem and depends on a User-like model.
 
-
-Generate User-like model:
+== Basics
+=== Generate User-like model:
 rails generate model User username:string email:string firstname:string \
 	lastname:string mobile_phone:string crypted_password:string password_salt:string \
-	session_id:string persistence_token:string login_count:string last_request_at:string \
+	session_id:string persistence_token:string login_count:integer last_request_at:string \
 	current_login_at:string last_login_at:string last_login_ip:string current_login_ip:string \
 	user_attributes:text refreshed_at:datetime
 
-Generate UserSession model
+=== Generate UserSession model
 rails generate authlogic:session user_session
 
-Create UserSessions controller
+=== Create UserSessions controller
 rails generate controller UserSessions --no-assets --no-helper
 
-Mixin authpds methods into UserSessionsController
+=== Mixin authpds methods into UserSessionsController
 class UserSessionsController < ApplicationController
-  include Authpds::Controllers::AuthpdsUserSessionsController
+	require 'authpds'
+  include Authpds::Controllers::AuthpdsSessionsController
 end
 
-Mixin authpds methods into ApplicationController
+=== Mixin authpds methods into ApplicationController
 class ApplicationController < ActionController::Base
   protect_from_forgery
   require 'authpds'
   include Authpds::Controllers::AuthpdsController
 end
+
+== Overview
+The Authpds gem mixes in callbacks to Authlogic for persisting
+sessions based on a valid PDS handle.  
+The module extends Authlogic and should be compatible with Authlogic configuation.
+It also provides hooks for custom functionality.
+The documentation below describes the hooks available for overriding, PDS config methods
+and further details about the module.
+
+== Config Options Available
+:pds_url:: Base pds url
+:calling_system:: Name of the system
+:anonymous:: Does the system allow anonymous access?
+:pds_attributes:: Mapping of PDS attributes to record attributes
+:redirect_logout_url:: Custom redirect logout url
+:login_inaccessible_url:: Custom url to redirect to in case of system outage
+:pds_record_identifier:: PDS user method to call to identify record
+:institution_param_key:: Querystring parameter key for the institution value in this system
+:validate_url_name:: URL name for validation action in routes
+
+== Hooks Available for Overriding
+:pds_record_identifier:: Allows for more complex logic in determining what should be used as the record identifier.
+Defaults to what was set in the pds_record_identifier config.
+:valid_sso_session?:: If there is no PDS handle, can we redirect to PDS to establish a SSO session based on some other information?
+:additional_authorization:: Allows for additions to the authorization decision
+:additional_attributes:: Allows for additional attributes to be stored in the record
+:expiration_date:: Indicates when the record information should be refreshed.  Defaults to one week ago.
+
+== Further Implementation Details 
+=== Persisting a Session in AuthLogic
+When persisting a Session, Authlogic attempts to create the Session based on information available 
+without having to perform an actual login by calling the :persisting? method. Authologic provides several callbacks from the :persisting?
+method, e.g. :before_persisting, :persist, :after_persisting.  We're using the :persist callback and setting it to :persist_session.
+
+=== Access to the controller in Session
+The class that Session extends, Authologic::Session::Base, has an explicit handle to the current controller via the instance method 
+:controller.  This gives our custom instance methods access to cookies, session information, loggers, etc. and also allows them to 
+perform redirects and renders.
+
+=== :before_login vs. :login_url
+:before_login allows for customized processing before the SessionController invokes a redirect or render to a /login page.  It is
+is fully generic and can be used for any custom purposes.  :login_url is specific for the case of logging in from a remote sytem.  The
+two methods can be used in conjuction, but any redirects or renders performed in :before_login, will supercede a redirect to :login_url.
+