From cc9301f459739e3eb3674b1b2e15057e35d25630 Mon Sep 17 00:00:00 2001 From: Matt Jankowski Date: Thu, 27 Jan 2011 12:25:22 -0500 Subject: clarify what the "they" that are is and what the "are" in question is --- actionpack/lib/action_dispatch/routing/mapper.rb | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'actionpack/lib') diff --git a/actionpack/lib/action_dispatch/routing/mapper.rb b/actionpack/lib/action_dispatch/routing/mapper.rb index f65a294eca..6658af15b0 100644 --- a/actionpack/lib/action_dispatch/routing/mapper.rb +++ b/actionpack/lib/action_dispatch/routing/mapper.rb @@ -827,7 +827,8 @@ module ActionDispatch alias :member_name :singular - # Checks for uncountable plurals, and appends "_index" if they're. + # Checks for uncountable plurals, and appends "_index" if the plural + # and singular form are the same. def collection_name singular == plural ? "#{plural}_index" : plural end -- cgit v1.2.3 From 49744bdaee899d64f8c70f65b2c1d63ace41cafa Mon Sep 17 00:00:00 2001 From: Jonathan Dance + Gabriel Horner Date: Fri, 28 Jan 2011 16:55:21 -0500 Subject: fix cross-references in HttpHelper methods --- actionpack/lib/action_dispatch/routing/mapper.rb | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'actionpack/lib') diff --git a/actionpack/lib/action_dispatch/routing/mapper.rb b/actionpack/lib/action_dispatch/routing/mapper.rb index 6658af15b0..af7a2c31f4 100644 --- a/actionpack/lib/action_dispatch/routing/mapper.rb +++ b/actionpack/lib/action_dispatch/routing/mapper.rb @@ -349,7 +349,7 @@ module ActionDispatch module HttpHelpers # Define a route that only recognizes HTTP GET. - # For supported arguments, see +match+. + # For supported arguments, see Base#match. # # Example: # @@ -359,7 +359,7 @@ module ActionDispatch end # Define a route that only recognizes HTTP POST. - # For supported arguments, see +match+. + # For supported arguments, see Base#match. # # Example: # @@ -369,7 +369,7 @@ module ActionDispatch end # Define a route that only recognizes HTTP PUT. - # For supported arguments, see +match+. + # For supported arguments, see Base#match. # # Example: # @@ -379,7 +379,7 @@ module ActionDispatch end # Define a route that only recognizes HTTP PUT. - # For supported arguments, see +match+. + # For supported arguments, see Base#match. # # Example: # -- cgit v1.2.3 From 38d728fb944b08b7faabf19c8ba5ef2e69e29c16 Mon Sep 17 00:00:00 2001 From: Jonathan Dance + Gabriel Horner Date: Fri, 28 Jan 2011 17:01:48 -0500 Subject: add cross-references and documentation for scope --- actionpack/lib/action_dispatch/routing.rb | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'actionpack/lib') diff --git a/actionpack/lib/action_dispatch/routing.rb b/actionpack/lib/action_dispatch/routing.rb index 8810227a59..43fd93adf6 100644 --- a/actionpack/lib/action_dispatch/routing.rb +++ b/actionpack/lib/action_dispatch/routing.rb @@ -56,6 +56,18 @@ module ActionDispatch # resources :posts, :comments # end # + # Alternately, you can add prefixes to your path without using a separate + # directory by using +scope+. +scope+ takes additional options which + # apply to all enclosed routes. + # + # scope :path => "/cpanel", :as => 'admin' do + # resources :posts, :comments + # end + # + # For more, see Routing::Mapper::Resources#resources, + # Routing::Mapper::Scoping#namespace, and + # Routing::Mapper::Scoping#scope. + # # == Named routes # # Routes can be named by passing an :as option, -- cgit v1.2.3 From ef48408a7bed075089999f588250f9710bca8f40 Mon Sep 17 00:00:00 2001 From: misfo Date: Sat, 29 Jan 2011 16:03:40 -0600 Subject: corrected the location of status code symbols --- actionpack/lib/action_dispatch/testing/assertions/response.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'actionpack/lib') diff --git a/actionpack/lib/action_dispatch/testing/assertions/response.rb b/actionpack/lib/action_dispatch/testing/assertions/response.rb index 1558c3ae05..77a15f3e97 100644 --- a/actionpack/lib/action_dispatch/testing/assertions/response.rb +++ b/actionpack/lib/action_dispatch/testing/assertions/response.rb @@ -20,7 +20,7 @@ module ActionDispatch # # You can also pass an explicit status number like assert_response(501) # or its symbolic equivalent assert_response(:not_implemented). - # See ActionDispatch::StatusCodes for a full list. + # See Rack::Utils::SYMBOL_TO_STATUS_CODE for a full list. # # ==== Examples # -- cgit v1.2.3 From fab16fded9a68cd327b6cfc5439ff10eed6df40b Mon Sep 17 00:00:00 2001 From: Jonathan Dance + Gabriel Horner Date: Sat, 29 Jan 2011 10:16:45 -0500 Subject: organize and expand on options for routing methods --- actionpack/lib/action_dispatch/routing/mapper.rb | 242 +++++++++++++++-------- 1 file changed, 161 insertions(+), 81 deletions(-) (limited to 'actionpack/lib') diff --git a/actionpack/lib/action_dispatch/routing/mapper.rb b/actionpack/lib/action_dispatch/routing/mapper.rb index af7a2c31f4..ee0fdce9dd 100644 --- a/actionpack/lib/action_dispatch/routing/mapper.rb +++ b/actionpack/lib/action_dispatch/routing/mapper.rb @@ -265,6 +265,78 @@ module ActionDispatch # controller in your application, and :action maps to the name of an # action within that controller. Anything other than :controller or # :action will be available to the action as part of params. + # + # === Supported options + # + # [:controller] + # The route's controller. + # + # [:action] + # The route's action. + # + # [:path] + # The path prefix for the routes. + # + # [:module] + # The namespace for :controller. + # + # match 'path' => 'c#a', :module => 'sekret', :controller => 'posts' + # #=> Sekret::PostsController + # + # See Scoping#namespace for its scope equivalent. + # + # [:as] + # The name used to generate routing helpers. + # + # [:via] + # Allowed HTTP verb(s) for route. + # + # match 'path' => 'c#a', :via => :get + # match 'path' => 'c#a', :via => [:get, :post] + # + # [:to] + # Shorthand for specifying :controller and :action. + # + # match 'path' => 'c#a', :to => 'controller#action' + # + # [:on] + # Shorthand for wrapping routes in a specific RESTful context. Valid + # values are :member, :collection, and :new. Only use within + # resource(s) block. For example: + # + # resource :bar do + # match 'foo' => 'c#a', :on => :member, :via => [:get, :post] + # end + # + # Is equivalent to: + # + # resource :bar do + # member do + # match 'foo' => 'c#a', :via => [:get, :post] + # end + # end + # + # [:constraints] + # Constrains parameters with a hash of regular expressions or an + # object that responds to #matches? + # + # match 'path/:id', :constraints => { :id => /[A-Z]\d{5}/ } + # + # class Blacklist + # def matches?(request) request.remote_ip == '1.2.3.4' end + # end + # match 'path' => 'c#a', :constraints => Blacklist.new + # + # See Scoping#constraints for more examples with its scope + # equivalent. + # + # [:defaults] + # Sets defaults for parameters + # + # # Sets params[:format] to 'jpg' by default + # match 'path' => 'c#a', :defaults => { :format => 'jpg' } + # + # See Scoping#defaults for its scope equivalent. def match(path, options=nil) mapping = Mapping.new(@set, @scope, path, options || {}).to_route @set.add_route(*mapping) @@ -458,7 +530,7 @@ module ActionDispatch super end - # Used to scope a set of routes to particular constraints. + # Scopes a set of routes to the given default options. # # Take the following route definition as an example: # @@ -471,50 +543,25 @@ module ActionDispatch # rather than /accounts/rails/projects/2. # # === Supported options - # [:module] - # If you want to route /posts (without the prefix /admin) to - # Admin::PostsController, you could use - # - # scope :module => "admin" do - # resources :posts - # end - # - # [:path] - # If you want to prefix the route, you could use - # - # scope :path => "/admin" do - # resources :posts - # end # - # This will prefix all of the +posts+ resource's requests with '/admin' + # Takes same options as Base#match and Resources#resources. # - # [:as] - # Prefixes the routing helpers in this scope with the specified label. - # - # scope :as => "sekret" do - # resources :posts - # end - # - # Helpers such as +posts_path+ will now be +sekret_posts_path+ - # - # [:shallow_path] - # - # Prefixes nested shallow routes with the specified path. + # === Examples # - # scope :shallow_path => "sekret" do - # resources :posts do - # resources :comments, :shallow => true - # end + # # route /posts (without the prefix /admin) to Admin::PostsController + # scope :module => "admin" do + # resources :posts + # end # - # The +comments+ resource here will have the following routes generated for it: + # # prefix the posts resource's requests with '/admin' + # scope :path => "/admin" do + # resources :posts + # end # - # post_comments GET /sekret/posts/:post_id/comments(.:format) - # post_comments POST /sekret/posts/:post_id/comments(.:format) - # new_post_comment GET /sekret/posts/:post_id/comments/new(.:format) - # edit_comment GET /sekret/comments/:id/edit(.:format) - # comment GET /sekret/comments/:id(.:format) - # comment PUT /sekret/comments/:id(.:format) - # comment DELETE /sekret/comments/:id(.:format) + # # prefix the routing helper name: sekret_posts_path instead of posts_path + # scope :as => "sekret" do + # resources :posts + # end def scope(*args) options = args.extract_options! options = options.dup @@ -577,43 +624,31 @@ module ActionDispatch # admin_post GET /admin/posts/:id(.:format) {:action=>"show", :controller=>"admin/posts"} # admin_post PUT /admin/posts/:id(.:format) {:action=>"update", :controller=>"admin/posts"} # admin_post DELETE /admin/posts/:id(.:format) {:action=>"destroy", :controller=>"admin/posts"} - # === Supported options - # - # The +:path+, +:as+, +:module+, +:shallow_path+ and +:shallow_prefix+ options all default to the name of the namespace. - # - # [:path] - # The path prefix for the routes. # - # namespace :admin, :path => "sekret" do - # resources :posts - # end - # - # All routes for the above +resources+ will be accessible through +/sekret/posts+, rather than +/admin/posts+ - # - # [:module] - # The namespace for the controllers. + # === Supported options # - # namespace :admin, :module => "sekret" do - # resources :posts - # end + # The +:path+, +:as+, +:module+, +:shallow_path+ and +:shallow_prefix+ + # options all default to the name of the namespace. # - # The +PostsController+ here should go in the +Sekret+ namespace and so it should be defined like this: + # For options, see Base#match. For +:shallow_path+ option, see + # Resources#resources. # - # class Sekret::PostsController < ApplicationController - # # code go here - # end + # === Examples # - # [:as] - # Changes the name used in routing helpers for this namespace. - # - # namespace :admin, :as => "sekret" do - # resources :posts - # end + # # accessible through /sekret/posts rather than /admin/posts + # namespace :admin, :path => "sekret" do + # resources :posts + # end # - # Routing helpers such as +admin_posts_path+ will now be +sekret_posts_path+. + # # maps to Sekret::PostsController rather than Admin::PostsController + # namespace :admin, :module => "sekret" do + # resources :posts + # end # - # [:shallow_path] - # See the +scope+ method. + # # generates sekret_posts_path rather than admin_posts_path + # namespace :admin, :as => "sekret" do + # resources :posts + # end def namespace(path, options = {}) path = path.to_s options = { :path => path, :as => path, :module => path, @@ -680,9 +715,9 @@ module ActionDispatch end # Allows you to set default parameters for a route, such as this: - # defaults :id => 'home' do - # match 'scoped_pages/(:id)', :to => 'pages#show' - # end + # defaults :id => 'home' do + # match 'scoped_pages/(:id)', :to => 'pages#show' + # end # Using this, the +:id+ parameter here will default to 'home'. def defaults(defaults = {}) scope(:defaults => defaults) { yield } @@ -907,6 +942,9 @@ module ActionDispatch # GET /geocoder/edit # PUT /geocoder # DELETE /geocoder + # + # === Supported options + # Takes same options as +resources+. def resource(*resources, &block) options = resources.extract_options! @@ -969,6 +1007,8 @@ module ActionDispatch # DELETE /photos/:id/comments/:id # # === Supported options + # Takes same options as Base#match as well as: + # # [:path_names] # Allows you to change the paths of the seven default actions. # Paths not specified are not changed. @@ -977,20 +1017,60 @@ module ActionDispatch # # The above example will now change /posts/new to /posts/brand_new # - # [:module] - # Set the module where the controller can be found. Defaults to nothing. + # [:only] + # Only generate routes for the given actions. # - # resources :posts, :module => "admin" + # resources :cows, :only => :show + # resources :cows, :only => [:show, :index] # - # All requests to the posts resources will now go to +Admin::PostsController+. + # [:except] + # Generate all routes except for the given actions. # - # [:path] + # resources :cows, :except => :show + # resources :cows, :except => [:show, :index] + # + # [:shallow] + # Generates shallow routes for nested resource(s). When placed on a parent resource, + # generates shallow routes for all nested resources. + # + # resources :posts, :shallow => true do + # resources :comments + # end + # + # Is the same as: + # + # resources :posts do + # resources :comments + # end + # resources :comments + # + # [:shallow_path] + # Prefixes nested shallow routes with the specified path. + # + # scope :shallow_path => "sekret" do + # resources :posts do + # resources :comments, :shallow => true + # end + # end + # + # The +comments+ resource here will have the following routes generated for it: + # + # post_comments GET /sekret/posts/:post_id/comments(.:format) + # post_comments POST /sekret/posts/:post_id/comments(.:format) + # new_post_comment GET /sekret/posts/:post_id/comments/new(.:format) + # edit_comment GET /sekret/comments/:id/edit(.:format) + # comment GET /sekret/comments/:id(.:format) + # comment PUT /sekret/comments/:id(.:format) + # comment DELETE /sekret/comments/:id(.:format) + # + # === Examples # - # Set a path prefix for this resource. + # # routes call Admin::PostsController + # resources :posts, :module => "admin" # - # resources :posts, :path => "admin" + # # resource actions are at /admin/posts. + # resources :posts, :path => "admin" # - # All actions for this resource will now be at +/admin/posts+. def resources(*resources, &block) options = resources.extract_options! -- cgit v1.2.3 From d1ef543794efdcc1d225055f88cbc88b20e84921 Mon Sep 17 00:00:00 2001 From: Jonathan Dance + Gabriel Horner Date: Sat, 29 Jan 2011 17:24:37 -0500 Subject: explain different ways to use match() --- actionpack/lib/action_dispatch/routing/mapper.rb | 25 +++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) (limited to 'actionpack/lib') diff --git a/actionpack/lib/action_dispatch/routing/mapper.rb b/actionpack/lib/action_dispatch/routing/mapper.rb index ee0fdce9dd..b28b68ad83 100644 --- a/actionpack/lib/action_dispatch/routing/mapper.rb +++ b/actionpack/lib/action_dispatch/routing/mapper.rb @@ -256,15 +256,22 @@ module ActionDispatch match '/', options.reverse_merge(:as => :root) end - # When you set up a regular route, you supply a series of symbols that - # Rails maps to parts of an incoming HTTP request. - # - # match ':controller/:action/:id/:user_id' - # - # Two of these symbols are special: :controller maps to the name of a - # controller in your application, and :action maps to the name of an - # action within that controller. Anything other than :controller or - # :action will be available to the action as part of params. + # Matches a pattern to one or more urls. Any symbols in a pattern are + # interpreted as url parameters: + # + # # sets parameters :controller, :action and :id + # match ':controller/:action/:id' + # + # Two of these symbols are special: :controller maps to the + # controller name and :action to the action name within that + # controller. Anything other than :controller or + # :action will be available to the action as part of +params+. + # If a pattern does not have :controller and :action symbols, then they + # must be set in options or shorthand. For example: + # + # match 'photos/:id' => 'photos#show' + # match 'photos/:id', :to => 'photos#show' + # match 'photos/:id', :controller => 'photos', :action => 'show' # # === Supported options # -- cgit v1.2.3 From 2446b1307ecf4ac13dc9ed3bcaf5a03ef3fcef98 Mon Sep 17 00:00:00 2001 From: Bernerd Schaefer Date: Wed, 2 Feb 2011 16:02:28 +0100 Subject: Provide documentation for ActionController::Metal --- actionpack/lib/action_controller/metal.rb | 60 ++++++++++++++++++++++++++++--- 1 file changed, 55 insertions(+), 5 deletions(-) (limited to 'actionpack/lib') diff --git a/actionpack/lib/action_controller/metal.rb b/actionpack/lib/action_controller/metal.rb index 329798e84f..0caf37b8cd 100644 --- a/actionpack/lib/action_controller/metal.rb +++ b/actionpack/lib/action_controller/metal.rb @@ -43,12 +43,62 @@ module ActionController end end - # Provides a way to get a valid Rack application from a controller. + # ActionController::Metal is the simplest possible controller, providing a + # valid Rack interface without the additional niceties provided by + # ActionController::Base. + # + # A sample Metal controller might look like this: + # + # class HelloController < ActionController::Metal + # def index + # self.response_body = "Hello World!" + # end + # end + # + # And then to route requests to your Metal controller, you would add + # something like this to config/routes.rb: + # + # match '/hello', :to => HelloController.action(:index), + # :as => 'hello' + # + # The action method returns a valid Rack application for the \Rails + # router to dispatch to. + # + # == Rendering Helpers + # + # ActionController::Metal by default provides no utilities for rendering + # views, partials, or other responses aside from explicitly calling of + # response_body=, content_type=, and status=. To + # add the render helpers you're used to having in a normal controller, you + # can do the following: + # + # class HelloController < ActionController::Metal + # include ActionController::Rendering + # append_view_path Rails.root + "app/views" + # + # def index + # render "hello/index" + # end + # end + # + # == Redirection Helpers + # + # To add redirection helpers to your Metal controller, do the following: + # + # class HelloController < ActionController::Metal + # include ActionController::Redirecting + # + # def index + # redirect_to root_url + # end + # end + # + # == Other Helpers + # + # You can refer to the modules defined in ActionController to see + # the other features in ActionController::Base that you can bring + # into your Metal controller. # - # In AbstractController, dispatching is triggered directly by calling #process on a new controller. - # ActionController::Metal provides an action method that returns a valid Rack application for a - # given action. Other rack builders, such as Rack::Builder, Rack::URLMap, and the \Rails router, - # can dispatch directly to actions returned by controllers in your application. class Metal < AbstractController::Base abstract! -- cgit v1.2.3