config/routes.rb you define URL-to-controller mappings, but
the reverse is also possible: a URL can be generated from one of your
routing definitions. URL generation functionality is centralized in this
See ActionDispatch::Routing for general information about routing and routes.rb.
Tip: If you need to generate URLs from your models or some other place, then ActionController::UrlFor is what you're looking for. Read on for an introduction. In general, this module should not be included on its own, as it is usually included by url_helpers (as in Rails.application.routes.url_helpers).
URL generation from parameters
As you may know, some functions, such as ActionController::Base#url_for and ActionView::Helpers::UrlHelper#link_to, can generate URLs given a set of parameters. For example, you've probably had the chance to write code like this in one of your views:
<%= link_to('Click here', controller: 'users', action: 'new', message: 'Welcome!') %> # => <a href="/users/new?message=Welcome%21">Click here</a>
link_to, and all other functions that require URL generation functionality, actually use ActionController::UrlFor under the hood. And in particular, they use the ActionController::UrlFor#url_for method. One can generate the same path as the above example by using the following code:
include UrlFor url_for(controller: 'users', action: 'new', message: 'Welcome!', only_path: true) # => "/users/new?message=Welcome%21"
only_path: true part. This is because UrlFor has no information about the website hostname
that your Rails app is serving. So if you want to include the hostname as
well, then you must also pass the
include UrlFor url_for(controller: 'users', action: 'new', message: 'Welcome!', host: 'www.example.com') # => "http://www.example.com/users/new?message=Welcome%21"
By default, all controllers and views have access to a special version of
#url_for, that already knows
what the current hostname is. So if you use #url_for in your controllers or
your views, then you don't need to explicitly pass the
For convenience reasons, mailers provide a shortcut for
ActionController::UrlFor#url_for. So within mailers, you only have to type
url_for instead of 'ActionController::UrlFor#url_for'
in full. However, mailers don't have hostname information, and you
still have to provide the
:host argument or set the default
host that will be used in all mailers using the configuration option
config.action_mailer.default_url_options. For more information
on #url_for in mailers read the
URL generation for named routes
UrlFor also allows one to access methods that
have been auto-generated from named routes. For example, suppose that you
have a 'users' resource in your
This generates, among other things, the method
default, this method is accessible from your controllers, views and
mailers. If you need to access this auto-generated method from other places
(such as a model), then you can do that by including Rails.application.routes.url_helpers
in your class:
class User < ActiveRecord::Base include Rails.application.routes.url_helpers def base_uri user_path(self) end end User.find(1).base_uri # => "/users/1"
# File actionpack/lib/action_dispatch/routing/url_for.rb, line 104 def initialize(*) @_routes = nil super end
Generate a url based on the options provided, default_url_options and the routes defined in routes.rb. The following options are supported:
:only_path- If true, the relative url is returned. Defaults to
:protocol- The protocol to connect to. Defaults to 'http'.
:host- Specifies the host the link should be targeted at. If
:only_pathis false, this option must be provided either explicitly, or via
:subdomain- Specifies the subdomain of the link, using the
tld_lengthto split the subdomain from the host. If false, removes all subdomains from the host part of the link.
:domain- Specifies the domain of the link, using the
tld_lengthto split the domain from the host.
:tld_length- Number of labels the TLD id composed of, only used if
:domainare supplied. Defaults to
ActionDispatch::Http::URL.tld_length, which in turn defaults to 1.
:port- Optionally specify the port to connect to.
:anchor- An anchor name to be appended to the path.
:trailing_slash- If true, adds a trailing slash, as in “/archive/2009/”
:script_name- Specifies application path relative to domain root. If provided, prepends application path.
Any other key (
:action, etc.) given
url_for is forwarded to the Routes module.
url_for controller: 'tasks', action: 'testing', host: 'somehost.org', port: '8080' # => 'http://somehost.org:8080/tasks/testing' url_for controller: 'tasks', action: 'testing', host: 'somehost.org', anchor: 'ok', only_path: true # => '/tasks/testing#ok' url_for controller: 'tasks', action: 'testing', trailing_slash: true # => 'http://somehost.org/tasks/testing/' url_for controller: 'tasks', action: 'testing', host: 'somehost.org', number: '33' # => 'http://somehost.org/tasks/testing?number=33' url_for controller: 'tasks', action: 'testing', host: 'somehost.org', script_name: "/myapp" # => 'http://somehost.org/myapp/tasks/testing' url_for controller: 'tasks', action: 'testing', host: 'somehost.org', script_name: "/myapp", only_path: true # => '/myapp/tasks/testing'
Missing routes keys may be filled in from the current request's
:id and any other parameters that are placed in the path).
Given that the current action has been reached through `GET /users/1`:
url_for(only_path: true) # => '/users/1' url_for(only_path: true, action: 'edit') # => '/users/1/edit' url_for(only_path: true, action: 'edit', id: 2) # => '/users/2/edit'
Notice that no
:id parameter was provided to the first
url_for call and the helper used the one from the route's
path. Any path parameter implicitly used by
url_for can always
be overwritten like shown on the last
# File actionpack/lib/action_dispatch/routing/url_for.rb, line 166 def url_for(options = nil) full_url_for(options) end
Hook overridden in controller to add request information with `default_url_options`. Application logic should not go into url_options.
# File actionpack/lib/action_dispatch/routing/url_for.rb, line 112 def url_options default_url_options end
# File actionpack/lib/action_dispatch/routing/url_for.rb, line 198 def optimize_routes_generation? _routes.optimize_routes_generation? && default_url_options.empty? end
# File actionpack/lib/action_dispatch/routing/url_for.rb, line 211 def _routes_context # :doc: self end
# File actionpack/lib/action_dispatch/routing/url_for.rb, line 204 def _with_routes(routes) # :doc: old_routes, @_routes = @_routes, routes yield ensure @_routes = old_routes end