модуль 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 212
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 168
def url_for(options = nil)
  full_url_for(options)
end

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

:only_path - Если true, возвращается относительный URL. По умолчанию false.
:protocol - Протокол подключения. По умолчанию 'http'.
:host - Указывает хост, на который должен быть направлен link. Если :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 - Имя якоря, которое будет добавлено к пути.
:trailing_slash - Если true, добавляет конечный слеш, как в «/archive/2009/»
:script_name - Указывает путь приложения относительно корня домена. Если указано, добавляет путь приложения.

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

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 и любые другие параметры, помещенные в путь). Учитывая, что текущее действие было достигнуто через 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 231
def _routes_context # :doc:
  self
end

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

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