Module: ActionDispatch::Routing::UrlFor
Relationships & Source Files | |
Extension / Inclusion / Inheritance Descendants | |
Included In:
::AbstractController::UrlFor ,
::ActionController::API ,
::ActionController::Base ,
::ActionController::Redirecting ,
::ActionController::UrlFor ,
::ActionDispatch::Integration::Session ,
RouteSet::MountedHelpers ,
ActionDispatch::Routing::RoutesProxy,
::ActionView::TestCase::TestController ,
Rails::ApplicationController,
::Rails::HealthController ,
Rails::InfoController,
Rails::MailersController,
Rails::WelcomeController
| |
Super Chains via Extension / Inclusion / Inheritance | |
Class Chain:
self,
::ActiveSupport::Concern
|
|
Instance Chain:
self,
PolymorphicRoutes
|
|
Defined in: | actionpack/lib/action_dispatch/routing/url_for.rb |
Overview
In 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 module.
See ::ActionDispatch::Routing
for general information about routing and config/routes.rb
.
Tip: If you need to generate URLs from your models or some other place, then 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 UrlFor
under the hood. And in particular, they use the #url_for method. One can generate the same path as the above example by using the following code:
include ActionDispatch::Routing::UrlFor
url_for(controller: 'users',
action: 'new',
message: 'Welcome!',
only_path: true)
# => "/users/new?message=Welcome%21"
Notice the 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 :host
argument:
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 :host
argument.
For convenience, mailers also include UrlFor
. So within mailers, you can use url_for. However, mailers cannot access incoming web requests in order to derive hostname information, so you have to provide the :host
option or set the default host using default_url_options
. For more information on url_for in mailers see the ::ActionMailer::Base
documentation.
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 config/routes.rb
:
resources :users
This generates, among other things, the method users_path
. By 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"
Class Method Summary
::ActiveSupport::Concern
- Extended
class_methods | Define class methods from given block. |
included | Evaluate given block in context of base class, so that you can write class macros here. |
prepended | Evaluate given block in context of base class, so that you can write class macros here. |
Instance Method Summary
- #initialize
-
#route_for(name, *args)
Allows calling direct or regular named route.
-
#url_for(options = nil)
Generate a URL based on the options provided,
default_url_options
, and the routes defined inconfig/routes.rb
. -
#url_options
Hook overridden in controller to add request information with
default_url_options
. - #_routes_context private
- #_with_routes(routes) private
PolymorphicRoutes
- Included
#polymorphic_path | Returns the path component of a URL for the given record. |
#polymorphic_url | Constructs a call to a named RESTful route for the given record and returns the resulting URL string. |
DSL Calls
included
[ GitHub ]93 94 95 96 97 98 99 100 101 102 103 104 105 106
# File 'actionpack/lib/action_dispatch/routing/url_for.rb', line 93
included do unless method_defined?(: ) # Including in a class uses an inheritable hash. Modules get a plain hash. if respond_to?(:class_attribute) class_attribute : else mattr_writer : end self. = {} end include(*_url_for_modules) if respond_to?(:_url_for_modules) end
Instance Method Details
#_routes_context (private)
[ GitHub ]# File 'actionpack/lib/action_dispatch/routing/url_for.rb', line 234
def _routes_context # :doc: self end
#_with_routes(routes) (private)
[ GitHub ]# File 'actionpack/lib/action_dispatch/routing/url_for.rb', line 227
def _with_routes(routes) # :doc: old_routes, @_routes = @_routes, routes yield ensure @_routes = old_routes end
#initialize
[ GitHub ]# File 'actionpack/lib/action_dispatch/routing/url_for.rb', line 108
def initialize(...) @_routes = nil super end
#route_for(name, *args)
Allows calling direct or regular named route.
resources :buckets
direct :recordable do |recording|
route_for(:bucket, recording.bucket)
end
direct :threadable do |threadable|
route_for(:recordable, threadable.parent)
end
This maintains the context of the original caller on whether to return a path or full URL, e.g:
threadable_path(threadable) # => "/buckets/1"
threadable_url(threadable) # => "http://example.com/buckets/1"
# File 'actionpack/lib/action_dispatch/routing/url_for.rb', line 217
def route_for(name, *args) public_send(:"#{name}_url", *args) end
#url_for(options = nil)
Generate a URL based on the options provided, default_url_options
, and the routes defined in config/routes.rb
. The following options are supported:
-
:only_path
- If true, the relative URL is returned. Defaults tofalse
. -
:protocol
- The protocol to connect to. Defaults to"http"
. -
:host
- Specifies the host the link should be targeted at. If:only_path
is false, this option must be provided either explicitly, or viadefault_url_options
. -
:subdomain
- Specifies the subdomain of the link, using thetld_length
to 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 thetld_length
to split the domain from the host. -
:tld_length
- Number of labels the TLD id composed of, only used if:subdomain
or:domain
are supplied. Defaults to 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. -
:params
- The query parameters to be appended to the path. -
:path_params
- The query parameters that will only be used for the named dynamic segments of path. If unused, they will be discarded. -
: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 (:controller
, :action
, etc.) given to 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 parameters (e.g. :controller
, :action
, :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 url_for
calls.
# File 'actionpack/lib/action_dispatch/routing/url_for.rb', line 173
def url_for( = nil) full_url_for( ) end
#url_options
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 116
def end