модуль ActionDispatch::Routing::UrlFor

Включенные модули:: ActionDispatch::Routing::PolymorphicRoutes

В config/routes.rb вы определяете сопоставления URL-адресов с контроллерами, но обратное также возможно: URL-адрес можно сгенерировать по одному из ваших определений маршрутов. Функциональность генерации URL-адресов централизована в этом модуле.

См. ActionDispatch::Routing для общей информации о маршрутизации и файле routes.rb.

Подсказка: Если вам нужно генерировать URL-адреса из ваших моделей или из другого места, то ActionController::UrlFor то, что вам нужно. Читайте дальше для введения. Как правило, этот модуль не следует включать самостоятельно, так как он обычно включается url_helpers (как в Rails.application.routes.url_helpers).

Генерация URL-адресов из параметров

Как вы знаете, некоторые функции, такие как ActionController::Base#url_for и ActionView::Helpers::UrlHelper#link_to, могут генерировать URL-адреса, заданные набором параметров. Например, вы, вероятно, имели возможность написать код подобный этому в одном из ваших представлений:

<%= link_to('Click here', controller: 'users',
        action: 'new', message: 'Welcome!') %>
# => <a href="/users/new?message=Welcome%21">Click here</a>

link_to и все другие функции, которые требуют функциональности генерации URL-адресов, фактически используют ActionController::UrlFor под капотом. И, в частности, они используют метод ActionController::UrlFor#url_for. Можно сгенерировать тот же путь, что и в приведенном выше примере, используя следующий код:

include UrlFor
url_for(controller: 'users',
        action: 'new',
        message: 'Welcome!',
        only_path: true)
# => "/users/new?message=Welcome%21"

Обратите внимание на only_path: true часть. Это потому, что UrlFor не имеет информации о хост-имени сайта, на котором работает ваша приложение Rails. Поэтому, если вы хотите включить также хост-имя, то вам необходимо также передать :host аргумент:

include UrlFor
url_for(controller: 'users',
        action: 'new',
        message: 'Welcome!',
        host: 'www.example.com')
# => "http://www.example.com/users/new?message=Welcome%21"

По умолчанию все контроллеры и представления имеют доступ к специальной версии url_for, которая уже знает текущее хост-имя. Таким образом, если вы используете url_for в своих контроллерах или представлениях, то вам не нужно явно передавать :host аргумент.

Для удобства, мейлеры предоставляют сокращенную запись для ActionController::UrlFor#url_for. Таким образом, в мейлерах вам нужно только набрать url_for вместо 'ActionController::UrlFor#url_for' полностью. Однако, мейлеры не имеют информации о хост-имени, и вам по-прежнему необходимо предоставить :host аргумент или установить значение по умолчанию для хоста, которое будет использоваться во всех мейлерах с помощью опции конфигурации config.action_mailer.default_url_options. Для получения дополнительной информации об url_for в мейлерах обратитесь к документации ActionMailer#Base.

Генерация URL-адресов для именованных маршрутов

UrlFor также позволяет получить доступ к методам, которые были сгенерированы автоматически из именованных маршрутов. Например, предположим, что у вас есть ресурс «users» в вашей config/routes.rb:

resources :users

Это генерирует, среди прочего, метод users_path. По умолчанию этот метод доступен из ваших контроллеров, представлений и мейлеров. Если вам нужно получить доступ к этому автоматически сгенерированному методу из других мест (например, модели), то вы можете сделать это, включив Rails.application.routes.url_helpers в свой класс:

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"

Общедоступные методы класса

new(...) Показать исходный код

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

Вызывает метод суперкласса

Общедоступные методы экземпляра

route_for(name, *args) Показать исходный код

# File actionpack/lib/action_dispatch/routing/url_for.rb, line 213
def route_for(name, *args)
  public_send(:"#{name}_url", *args)
end

Позволяет вызывать прямой или обычный именованный маршрут.

resources :buckets

direct :recordable do |recording|
  route_for(:bucket, recording.bucket)
end

direct :threadable do |threadable|
  route_for(:recordable, threadable.parent)
end

Это сохраняет контекст исходного вызывающего объекта относительно возврата пути или полного URL-адреса, например:

threadable_path(threadable)  # => "/buckets/1"
threadable_url(threadable)   # => "http://example.com/buckets/1"

url_for(options = nil) Показать исходный код

# File actionpack/lib/action_dispatch/routing/url_for.rb, line 169
def url_for(options = nil)
  full_url_for(options)
end

Генерирует URL-адрес на основе предоставленных параметров, default_url_options и маршрутов, определённых в routes.rb. Поддерживаются следующие параметры:

:only_path - Если true, возвращается относительный URL-адрес. По умолчанию false.
:protocol - Протокол соединения. По умолчанию 'http'.
:host - Указывает хост, к которому должен быть направлен ссылка. Если :only_path является false, этот параметр должен быть предоставлен явно или через default_url_options.
:subdomain - Указывает поддомен ссылки, используя tld_length для разделения поддомена от хоста. Если false, удаляет все поддомены из части хоста ссылки.
:domain - Указывает домен ссылки, используя tld_length для разделения домена от хоста.
:tld_length - Количество меток, из которых состоит TLD, используется только если :subdomain или :domain заданы. По умолчанию ActionDispatch::Http::URL.tld_length, которое по умолчанию равно 1.
:port - Необязательно укажите порт для соединения.
:anchor - Имя якоря, которое будет добавлено к пути.
:params - Параметры запроса, которые будут добавлены к пути.
:trailing_slash - Если true, добавляет конечный слэш, как в «/archive/2009/»
:script_name - Указывает путь приложения относительно корня домена. Если указано, добавляет путь приложения.

Любой другой ключ (:controller, :action, и т.д.) заданный для url_for передаётся в модуль Routes.

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'

Пропущенные ключи маршрутов могут быть заполнены из параметров текущего запроса (например, :controller, :action, :id и любые другие параметры, которые размещаются в пути). Учитывая, что текущий action был достигнут через 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'

Обратите внимание, что параметр :id не был предоставлен первому вызову url_for, и помощник использовал параметр из пути маршрута. Любой параметр пути, который неявно используется url_for, всегда может быть переопределён, как показано на последних вызовах url_for.

url_options() Показать исходный код

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

Переопределённый в контроллере хук для добавления информации о запросе с default_url_options. Логика приложения не должна входить в url_options.

Защищённые методы экземпляра

optimize_routes_generation?() Показать исходный код

# File actionpack/lib/action_dispatch/routing/url_for.rb, line 218
def optimize_routes_generation?
  _routes.optimize_routes_generation? && default_url_options.empty?
end

Приватные методы экземпляра

_routes_context() Показать исходный код

# File actionpack/lib/action_dispatch/routing/url_for.rb, line 230
def _routes_context # :doc:
  self
end

_with_routes(routes) { || ... } Показать исходный код

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