From 0bd7b07dff253e0fc2d01644371680bafa0df372 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rafael=20Mendon=C3=A7a=20Fran=C3=A7a?=
 <rafaelmfranca@gmail.com>
Date: Fri, 10 Aug 2012 00:06:16 -0300
Subject: [PATCH] Add CHANGELOG entry and documentation for Routing Concerns

---
 actionpack/CHANGELOG.md                       | 30 +++++++++++++++
 .../lib/action_dispatch/routing/mapper.rb     | 38 +++++++++++++++++++
 guides/source/routing.textile                 | 30 +++++++++++++++
 3 files changed, 98 insertions(+)

diff --git a/actionpack/CHANGELOG.md b/actionpack/CHANGELOG.md
index 2e683e7c47..d674fae9d4 100644
--- a/actionpack/CHANGELOG.md
+++ b/actionpack/CHANGELOG.md
@@ -1,5 +1,35 @@
 ## Rails 4.0.0 (unreleased) ##
 
+*   Add Routing Concerns to declare common routes that can be reused inside
+    others resources and routes.
+
+    Code before:
+
+        resources :messages do
+          resources :comments
+        end
+
+        resources :posts do
+          resources :comments
+          resources :images, only: :index
+        end
+
+    Code after:
+
+        concern :commentable do
+          resources :comments
+        end
+
+        concern :image_attachable do
+          resources :images, only: :index
+        end
+
+        resources :messages, concerns: :commentable
+
+        resources :posts, concerns: [:commentable, :image_attachable]
+
+    *David Heinemeier Hansson + Rafael Mendonça França*
+
 *   Add start_hour and end_hour options to the select_hour helper. *Evan Tann*
 
 *   Raises an ArgumentError when the first argument in `form_for` contain `nil`
diff --git a/actionpack/lib/action_dispatch/routing/mapper.rb b/actionpack/lib/action_dispatch/routing/mapper.rb
index 5ff2420921..ea5028a7c0 100644
--- a/actionpack/lib/action_dispatch/routing/mapper.rb
+++ b/actionpack/lib/action_dispatch/routing/mapper.rb
@@ -1584,11 +1584,49 @@ def name_for_action(as, action) #:nodoc:
           end
       end
 
+      # Routing Concerns allows you to declare common routes that can be reused
+      # inside others resources and routes.
+      #
+      #   concern :commentable do
+      #     resources :comments
+      #   end
+      #
+      #   concern :image_attachable do
+      #     resources :images, only: :index
+      #   end
+      #
+      # These concerns are used in Resources routing:
+      #
+      #   resources :messages, concerns: [:commentable, :image_attachable]
+      #
+      # or in a scope or namespace:
+      #
+      #   namespace :posts do
+      #     concerns :commentable
+      #   end
       module Concerns
+        # Define a routing concern using a name.
+        #
+        #   concern :commentable do
+        #     resources :comments
+        #   end
+        #
+        # Any routing helpers can be used inside a concern.
         def concern(name, &block)
           @concerns[name] = block
         end
 
+        # Use the named concerns
+        #
+        #   resources :posts do
+        #     concerns :commentable
+        #   end
+        #
+        # concerns also work in any routes helper that you want to use:
+        #
+        #   namespace :posts do
+        #     concerns :commentable
+        #   end
         def concerns(*names)
           names.flatten.each do |name|
             if concern = @concerns[name]
diff --git a/guides/source/routing.textile b/guides/source/routing.textile
index cffbf9bec4..bed7d03e06 100644
--- a/guides/source/routing.textile
+++ b/guides/source/routing.textile
@@ -273,6 +273,36 @@ The corresponding route helper would be +publisher_magazine_photo_url+, requirin
 
 TIP: _Resources should never be nested more than 1 level deep._
 
+h4. Routing concerns
+
+Routing Concerns allows you to declare common routes that can be reused inside others resources and routes.
+
+<ruby>
+concern :commentable do
+  resources :comments
+end
+
+concern :image_attachable do
+  resources :images, only: :index
+end
+</ruby>
+
+These concerns can be used in resources to avoid code duplication and share behavior across routes.
+
+<ruby>
+resources :messages, concerns: :commentable
+
+resources :posts, concerns: [:commentable, :image_attachable]
+</ruby>
+
+Also you can use them in any place that you want inside the routes, for example in a scope or namespace call:
+
+<ruby>
+namespace :posts do
+  concerns :commentable
+end
+</ruby>
+
 h4. Creating Paths and URLs From Objects
 
 In addition to using the routing helpers, Rails can also create paths and URLs from an array of parameters. For example, suppose you have this set of routes:
-- 
GitLab