module ActionDispatch::Routing::UrlFor - actionpack-3.2.22 Documentation

# module ActionDispatch::Routing::UrlFor

In `config/routes.rb` you define URL-to-controller mappings, but the reverse is also possible: an 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 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.

## 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!') %>
    # => "/users/new?message=Welcome%21"

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"

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 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 that’s why you’ll still have to specify the `:host` argument when generating URLs in mailers.

## 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 ActionController::UrlFor 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"

### Public Class Methods

new(*) click to toggle source
Calls superclass method

    # File lib/action_dispatch/routing/url_for.rb, line 101
    def initialize(*)
      @_routes = nil
      super
    end

### Public Instance Methods

url_for(options = nil) click to toggle source

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 `false`.

- `: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 via `default_url_options`.

- `:subdomain` - Specifies the subdomain of the link, using the `tld_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 the `tld_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 `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/"

Any other key (`:controller`, `:action`, etc.) given to `url_for` is forwarded to the Routes module.

Examples:

    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'

    # File lib/action_dispatch/routing/url_for.rb, line 143
    def url_for(options = nil)
      case options
      when String
        options
      when nil, Hash
        _routes.url_for((options || {}).symbolize_keys.reverse_merge!(url_options))
      else
        polymorphic_url(options)
      end
    end

url_options() click to toggle source

    # File lib/action_dispatch/routing/url_for.rb, line 106
    def url_options
      default_url_options
    end

### Protected Instance Methods

_routes_context() click to toggle source

    # File lib/action_dispatch/routing/url_for.rb, line 162
    def _routes_context
      self
    end

_with_routes(routes) { || ... } click to toggle source

    # File lib/action_dispatch/routing/url_for.rb, line 155
    def _with_routes(routes)
      old_routes, @_routes = @_routes, routes
      yield
    ensure
      @_routes = old_routes
    end