Add documentation for after login redirects

guides/source/developers/customizations/customizing-after-login-redirects.html.md

@@ -0,0 +1,56 @@
+# Customizing After-login Redirects
+
+Standard Solidus installations use the `solidus_auth_devise` gem
+in order to provide user authentication. The gem is based on
+`Devise`, a very successful authentication gem for Rails.
+
+When the unauthenticated user visits an authentication-protected page, they're
+first redirected to the login page, eventually after successful login they're
+redirected back to the page they were originally wanting to visit.
+
+Before redirecting the user to the login page, Solidus stores the original URL
+that the user wanted to visit into Rails application session cookie, ie.
+`session[:spree_return_to]`.
+
+There are some URLs that we need to avoid storing in session, othwewise
+inifite-loops would occur after successful authentication.
+
+All of these URLs with a standard  Solidus installation are related to the
+authentication process, but you may need to add more, for example because you
+added some more authentication URLs.
+
+Solidus uses rules managed by the service object [`Spree::UrlReturnToStorer`][user-return-to-storer]
+in order to decide whether the current path should be stored or not. The
+default rule is defined in [`Spree::UrlReturnToStorer::Rules::AuthenticationRule`][auth-rule].
+
+In order to add your custom behavior, you can create a new rule:
+
+```ruby
+module Spree
+  class UserReturnToStorer
+    module Rules
+      module FacebookLoginRule
+        extend self
+
+        def match?(controller)
+          controller.controller_name == "sessions" &&
+            action_name == "facebook_login"
+        end
+      end
+    end
+  end
+end
+```
+
+After that, you need to register your new rule module, for example by adding
+this line in `config/spree.rb` file:
+
+```ruby
+Spree::UserReturnToStorer.rules << 'Spree::UrlReturnToStorer::Rules::CustomRule'
+```
+
+Please note that, when at least one rule is met (`#match?` returns `true`) then
+the current path **is not** stored in the session.
+
+[user-return-to-storer]: https://github.com/solidusio/solidus/blob/master/core/app/models/spree/user_return_to_storer.rb
+[auth-rule]: https://github.com/solidusio/solidus/blob/master/core/app/models/spree/user_return_to_storer/rules/authentication_rule.rb

guides/source/developers/customizations/overview.html.md

@@ -17,10 +17,12 @@ and the framework that power Solidus, respectively.
 - [Learn How to Customize the Assets][assets]
 - [Learn How to Customize the Permissions][permissions]
 - [Learn How to Customize Model Attributes][attributes]
+- [Learn How to Customize After-login Redirects][after-login-redirects]
 
 [storefront]: customizing-storefront.html
 [admin]: customizing-admin.html
 [assets]: customizing-assets.html
 [decorators]: decorators.html
 [permissions]: customizing-permissions.html
-[attributes]: customizing-attributes.html
+[attributes]: customizing-attributes.html
+[after-login-redirects]: customizing-after-login-redirects.html