Skip to content
This repository
tree: c41f08cefe
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 168 lines (160 sloc) 7.169 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167
module ActionDispatch
  module Routing
    # In <tt>config/routes.rb</tt> 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.
    #
    # <b>Tip:</b> 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 <tt>:only_path => true</tt> 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 <tt>:host</tt>
    # 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 <tt>:host</tt>
    # 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 <tt>:host</tt> 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
    # <tt>config/routes.rb</tt>:
    #
    # resources :users
    #
    # This generates, among other things, the method <tt>users_path</tt>. 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"
    #
    module UrlFor
      extend ActiveSupport::Concern
      include PolymorphicRoutes

      included do
        # TODO: with_routing extends @controller with url_helpers, trickling down to including this module which overrides its default_url_options
        unless method_defined?(:default_url_options)
          # Including in a class uses an inheritable hash. Modules get a plain hash.
          if respond_to?(:class_attribute)
            class_attribute :default_url_options
          else
            mattr_accessor :default_url_options
            remove_method :default_url_options
          end

          self.default_url_options = {}
        end
      end

      def initialize(*)
        @_routes = nil
        super
      end

      def url_options
        default_url_options
      end

      # Generate a url based on the options provided, default_url_options and the
      # routes defined in routes.rb. The following options are supported:
      #
      # * <tt>:only_path</tt> - If true, the relative url is returned. Defaults to +false+.
      # * <tt>:protocol</tt> - The protocol to connect to. Defaults to 'http'.
      # * <tt>:host</tt> - Specifies the host the link should be targeted at.
      # If <tt>:only_path</tt> is false, this option must be
      # provided either explicitly, or via +default_url_options+.
      # * <tt>:subdomain</tt> - 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.
      # * <tt>:domain</tt> - Specifies the domain of the link, using the +tld_length+
      # to split the domain from the host.
      # * <tt>:tld_length</tt> - Number of labels the TLD id composed of, only used if
      # <tt>:subdomain</tt> or <tt>:domain</tt> are supplied. Defaults to
      # <tt>ActionDispatch::Http::URL.tld_length</tt>, which in turn defaults to 1.
      # * <tt>:port</tt> - Optionally specify the port to connect to.
      # * <tt>:anchor</tt> - An anchor name to be appended to the path.
      # * <tt>:trailing_slash</tt> - If true, adds a trailing slash, as in "/archive/2009/"
      #
      # Any other key (<tt>:controller</tt>, <tt>:action</tt>, 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'
      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

      protected
        def _with_routes(routes)
          old_routes, @_routes = @_routes, routes
          yield
        ensure
          @_routes = old_routes
        end

        def _routes_context
          self
        end
    end
  end
end
Something went wrong with that request. Please try again.