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.

1 files changed, 29 insertions, 0 deletions

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