Added documentation explaining the new additional supported syntaxes for the routing redirect method, a small changelog note, and two extra tests for path interpolation when using the hash option syntax.

3 files changed, 48 insertions, 0 deletions

diff --git a/actionpack/CHANGELOG b/actionpack/CHANGELOG
index 74d017cc3d..9b292cca69 100644
--- a/actionpack/CHANGELOG
+++ b/actionpack/CHANGELOG
@@ -1,5 +1,7 @@
 *Rails 3.1.0 (unreleased)*
 
+* The redirect route method now also accepts a hash of options which will only change the parts of the url in question, or an object which responds to call, allowing for redirects to be reused (check the documentation for examples). [Josh Kalderimis]
+
 * Added config.action_controller.include_all_helpers. By default 'helper :all' is done in ActionController::Base, which includes all the helpers by default. Setting include_all_helpers to false will result in including only application_helper and helper corresponding to controller (like foo_helper for foo_controller). [Piotr Sarnacki]
 
 * Added a convenience idiom to generate HTML5 data-* attributes in tag helpers from a :data hash of options:
diff --git a/actionpack/lib/action_dispatch/routing/redirection.rb b/actionpack/lib/action_dispatch/routing/redirection.rb
index d9c9a400a7..804991ad5f 100644
--- a/actionpack/lib/action_dispatch/routing/redirection.rb
+++ b/actionpack/lib/action_dispatch/routing/redirection.rb
@@ -7,6 +7,35 @@ module ActionDispatch
       # Redirect any path to another path:
       #
       #   match "/stories" => redirect("/posts")
+      #
+      # You can also use interpolation in the supplied redirect argument:
+      #
+      #   match 'docs/:article', :to => redirect('/wiki/%{article}')
+      #
+      # Alternatively you can use one of the other syntaxes:
+      #
+      # The block version of redirect allows for the easy encapsulation of any logic associated with
+      # the redirect in question. Either the params and request are supplied as arguments, or just
+      # params, depending of how many arguments your block accepts. A string is required as a
+      # return value.
+      #
+      #   match 'jokes/:number', :to => redirect do |params, request|
+      #     path = (params[:number].to_i.even? ? "/wheres-the-beef" : "/i-love-lamp")
+      #     "http://#{request.host_with_port}/#{path}"
+      #   end
+      #
+      # The options version of redirect allows you to supply only the parts of the url which need
+      # to change, it also supports interpolation of the path similar to the first example.
+      #
+      #   match 'stores/:name',       :to => redirect(:subdomain => 'stores', :path => '/%{name}')
+      #   match 'stores/:name(*all)', :to => redirect(:subdomain => 'stores', :path => '/%{name}%{all}')
+      #
+      # Finally, an object which responds to call can be supplied to redirect, allowing you to reuse
+      # common redirect routes. The call method must accept two arguments, params and request, and return
+      # a string.
+      #
+      #   match 'accounts/:name' => redirect(SubdomainRedirector.new('api'))
+      #
       def redirect(*args, &block)
         options = args.last.is_a?(Hash) ? args.pop : {}
         status  = options.delete(:status) || 301
diff --git a/actionpack/test/dispatch/routing_test.rb b/actionpack/test/dispatch/routing_test.rb
index 74420317c7..4bf7880294 100644
--- a/actionpack/test/dispatch/routing_test.rb
+++ b/actionpack/test/dispatch/routing_test.rb
@@ -65,6 +65,9 @@ class TestRoutingMapper < ActionDispatch::IntegrationTest
       match 'new_documentation', :to => redirect(:path => '/documentation/new')
       match 'super_new_documentation', :to => redirect(:host => 'super-docs.com')
 
+      match 'stores/:name',        :to => redirect(:subdomain => 'stores', :path => '/%{name}')
+      match 'stores/:name(*rest)', :to => redirect(:subdomain => 'stores', :path => '/%{name}%{rest}')
+
       match 'youtube_favorites/:youtube_id/:name', :to => redirect(YoutubeFavoritesRedirector)
 
       constraints(lambda { |req| true }) do
@@ -708,6 +711,20 @@ class TestRoutingMapper < ActionDispatch::IntegrationTest
     end
   end
 
+  def test_redirect_hash_path_substitution
+    with_test_routes do
+      get '/stores/iernest'
+      verify_redirect 'http://stores.example.com/iernest'
+    end
+  end
+
+  def test_redirect_hash_path_substitution_with_catch_all
+    with_test_routes do
+      get '/stores/iernest/products'
+      verify_redirect 'http://stores.example.com/iernest/products'
+    end
+  end
+
   def test_redirect_class
     with_test_routes do
       get '/youtube_favorites/oHg5SJYRHA0/rick-rolld'