The routing module provides URL rewriting in native Ruby. It's a way to
redirect incoming requests to controllers and actions. This replaces
mod_rewrite rules. Best of all, Rails' Routing works with any web
server. Routes are defined in config/routes.rb
.
Think of creating routes as drawing a map for your requests. The map tells them where to go based on some predefined pattern:
Rails.application.routes.draw do
Pattern 1 tells some request to go to one place
Pattern 2 tell them to go to another
...
end
The following symbols are special:
:controller maps to your controller name
:action maps to an action with your controllers
Other names simply map to a parameter as in the case of :id
.
Resources
Resource routing allows you to quickly declare all of the common routes for
a given resourceful controller. Instead of declaring separate routes for
your index
, show
, new
,
edit
, create
, update
and
destroy
actions, a resourceful route declares them in a single
line of code:
resources :photos
Sometimes, you have a resource that clients always look up without referencing an ID. A common example, /profile always shows the profile of the currently logged in user. In this case, you can use a singular resource to map /profile (rather than /profile/:id) to the show action.
resource :profile
It's common to have resources that are logically children of other resources:
resources :magazines do
resources :ads
end
You may wish to organize groups of controllers under a namespace. Most
commonly, you might group a number of administrative controllers under an
admin
namespace. You would place these controllers under the
app/controllers/admin
directory, and you can group them
together in your router:
namespace "admin" do
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
.
Non-resourceful routes
For routes that don't fit the resources
mold, you can use
the HTTP helper methods get
, post
,
patch
, put
and delete
.
get 'post/:id' => 'posts#show'
post 'post/:id' => 'posts#create_comment'
If your route needs to respond to more than one HTTP method (or all
methods) then using the :via
option on match
is
preferable.
match 'post/:id' => 'posts#show', via: [:get, :post]
Now, if you POST to /posts/:id
, it will route to the
create_comment
action. A GET on the same URL will route to the
show
action.
Named routes
Routes can be named by passing an :as
option, allowing for
easy reference within your source as name_of_route_url
for the
full URL and name_of_route_path
for the URI path.
Example:
# In routes.rb
get '/login' => 'accounts#login', as: 'login'
# With render, redirect_to, tests, etc.
redirect_to login_url
Arguments can be passed as well.
redirect_to show_item_path(id: 25)
Use root
as a shorthand to name a route for the root path “/”.
# In routes.rb
root to: 'blogs#index'
# would recognize http://www.example.com/ as
params = { controller: 'blogs', action: 'index' }
# and provide these named routes
root_url # => 'http://www.example.com/'
root_path # => '/'
Note: when using controller
, the route is simply named after
the method you call on the block parameter rather than map.
# In routes.rb
controller :blog do
get 'blog/show' => :list
get 'blog/delete' => :delete
get 'blog/edit/:id' => :edit
end
# provides named routes for show, delete, and edit
link_to @article.title, show_path(id: @article.id)
Pretty URLs
Routes can generate pretty URLs. For example:
get '/articles/:year/:month/:day' => 'articles#find_by_id', constraints: {
year: /\d{4}/,
month: /\d{1,2}/,
day: /\d{1,2}/
}
Using the route above, the URL “localhost:3000/articles/2005/11/06” maps to
params = {year: '2005', month: '11', day: '06'}
Regular Expressions and parameters
You can specify a regular expression to define a format for a parameter.
controller 'geocode' do
get 'geocode/:postalcode' => :show, constraints: {
postalcode: /\d{5}(-\d{4})?/
}
Constraints can include the 'ignorecase' and 'extended syntax' regular expression modifiers:
controller 'geocode' do
get 'geocode/:postalcode' => :show, constraints: {
postalcode: /hx\d\d\s\d[a-z]{2}/i
}
end
controller 'geocode' do
get 'geocode/:postalcode' => :show, constraints: {
postalcode: /# Postcode format
\d{5} #Prefix
(-\d{4})? #Suffix
/x
}
end
Using the multiline modifier will raise an ArgumentError
. Encoding regular expression modifiers are
silently ignored. The match will always use the default encoding or ASCII.
External redirects
You can redirect any path to another path using the redirect helper in your router:
get "/stories" => redirect("/posts")
Unicode character routes
You can specify unicode character routes in your router:
get "こんにちは" => "welcome#index"
Routing to Rack Applications
Instead of a String, like
posts#index
, which corresponds to the index action in the
PostsController, you can specify any Rack
application as the endpoint for a matcher:
get "/application.js" => Sprockets
Reloading routes
You can reload routes if you feel you must:
Rails.application.reload_routes!
This will clear all named routes and reload routes.rb if the file has been
modified from last load. To absolutely force reloading, use
reload!
.
Testing Routes
The two main methods for testing your routes:
assert_routing
def test_movie_route_properly_splits
opts = {controller: "plugin", action: "checkout", id: "2"}
assert_routing "plugin/checkout/2", opts
end
assert_routing
lets you test whether or not the route properly
resolves into options.
assert_recognizes
def test_route_has_options
opts = {controller: "plugin", action: "show", id: "12"}
assert_recognizes opts, "/plugins/show/12"
end
Note the subtle difference between the two: assert_routing
tests that a URL fits options while assert_recognizes
tests
that a URL breaks into parameters properly.
In tests you can simply pass the URL or named route to get
or
post
.
def send_to_jail
get '/jail'
assert_response :success
assert_template "jail/front"
end
def goes_to_login
get login_url
#...
end
View a list of all your routes
rake routes
Target specific controllers by prefixing the command with
CONTROLLER=x
.
- MODULE ActionDispatch::Routing::PolymorphicRoutes
- MODULE ActionDispatch::Routing::Redirection
- MODULE ActionDispatch::Routing::UrlFor
- CLASS ActionDispatch::Routing::ConsoleFormatter
- CLASS ActionDispatch::Routing::HtmlTableFormatter
- CLASS ActionDispatch::Routing::Mapper
- CLASS ActionDispatch::Routing::PathRedirect
- CLASS ActionDispatch::Routing::RouteWrapper
SEPARATORS | = | %w( / . ? ) |
HTTP_METHODS | = | [:get, :head, :post, :patch, :put, :delete, :options] |