модуль ActionView::Helpers::UrlHelper

# File actionview/lib/action_view/helpers/url_helper.rb, line 300
def button_to(name = nil, options = nil, html_options = nil, &block)
  html_options, options = options, name if block_given?
  options      ||= {}
  html_options ||= {}
  html_options = html_options.stringify_keys

  url    = options.is_a?(String) ? options : url_for(options)
  remote = html_options.delete("remote")
  params = html_options.delete("params")

  method     = html_options.delete("method").to_s
  method_tag = BUTTON_TAG_METHOD_VERBS.include?(method) ? method_tag(method) : "".freeze.html_safe

  form_method  = method == "get" ? "get" : "post"
  form_options = html_options.delete("form") || {}
  form_options[:class] ||= html_options.delete("form_class") || "button_to"
  form_options[:method] = form_method
  form_options[:action] = url
  form_options[:'data-remote'] = true if remote

  request_token_tag = if form_method == "post"
    request_method = method.empty? ? "post" : method
    token_tag(nil, form_options: { action: url, method: request_method })
  else
    "".freeze
  end

  html_options = convert_options_to_data_attributes(options, html_options)
  html_options["type"] = "submit"

  button = if block_given?
    content_tag("button", html_options, &block)
  else
    html_options["value"] = name || url
    tag("input", html_options)
  end

  inner_tags = method_tag.safe_concat(button).safe_concat(request_token_tag)
  if params
    to_form_params(params).each do |param|
      inner_tags.safe_concat tag(:input, type: "hidden", name: param[:name], value: param[:value])
    end
  end
  content_tag("form", inner_tags, form_options)
end

Генерирует форму, содержащую одну кнопку, которая отправляет данные на URL, созданный набором options. Это самый безопасный метод, гарантирующий, что ссылки, вызывающие изменения в ваших данных, не будут активированы ботами поиска или ускорителями. Если кнопка HTML не работает с вашей разметкой, вы также можете рассмотреть использование метода link_to с модификатором :method, как описано в документации link_to.

По умолчанию сгенерированный элемент формы имеет имя класса button_to, чтобы позволить стилизацию самой формы и её дочерних элементов. Это можно изменить с помощью модификатора :form_class в html_options. Вы можете управлять поведением отправки формы и элемента ввода с помощью html_options. Этот метод принимает модификатор :method, описанный в документации link_to. Если модификатор :method не указан, по умолчанию выполняется операция POST. Вы также можете отключить кнопку, передав disabled: true в html_options. Если вы используете RESTful маршруты, вы можете передать :method для изменения HTTP-метода, используемого для отправки формы.

Параметры

Хэш options принимает те же параметры, что и url_for.

Есть несколько специальных html_options:

• :method - Символ HTTP-метода. Поддерживаемые методы: :post, :get, :delete, :patch, и :put. По умолчанию используется :post.

• :disabled - Если установлено в true, будет сгенерирована отключенная кнопка.

• :data - Этот параметр можно использовать для добавления пользовательских атрибутов данных.

• :remote - Если установлено в true, это позволит драйверам JavaScript управлять поведением отправки. По умолчанию это ajax-отправка.

• :form - Этот хэш будет атрибутами формы.

• :form_class - Это определяет класс формы, в которой будет размещена кнопка отправки.

• :params - Хэш параметров, которые будут отображены как скрытые поля в форме.

Атрибуты данных

• :confirm - Этот параметр использует драйвер unobtrusive JavaScript для вывода запроса с указанным вопросом. Если пользователь соглашается, ссылка обрабатывается обычно, в противном случае никаких действий не выполняется.

• :disable_with - Значение этого параметра будет использоваться в качестве значения для отключенной версии кнопки отправки при отправке формы. Эта функция предоставляется драйвером unobtrusive JavaScript.

Примеры

<%= button_to "New", action: "new" %>
# => "<form method="post" action="/controller/new" class="button_to">
#      <input value="New" type="submit" />
#    </form>"

<%= button_to "New", new_articles_path %>
# => "<form method="post" action="/articles/new" class="button_to">
#      <input value="New" type="submit" />
#    </form>"

<%= button_to [:make_happy, @user] do %>
  Make happy <strong><%= @user.name %></strong>
<% end %>
# => "<form method="post" action="/users/1/make_happy" class="button_to">
#      <button type="submit">
#        Make happy <strong><%= @user.name %></strong>
#      </button>
#    </form>"

<%= button_to "New", { action: "new" }, form_class: "new-thing" %>
# => "<form method="post" action="/controller/new" class="new-thing">
#      <input value="New" type="submit" />
#    </form>"

<%= button_to "Create", { action: "create" }, remote: true, form: { "data-type" => "json" } %>
# => "<form method="post" action="/images/create" class="button_to" data-remote="true" data-type="json">
#      <input value="Create" type="submit" />
#      <input name="authenticity_token" type="hidden" value="10f2163b45388899ad4d5ae948988266befcb6c3d1b2451cf657a0c293d605a6"/>
#    </form>"

<%= button_to "Delete Image", { action: "delete", id: @image.id },
                                method: :delete, data: { confirm: "Are you sure?" } %>
# => "<form method="post" action="/images/delete/1" class="button_to">
#      <input type="hidden" name="_method" value="delete" />
#      <input data-confirm='Are you sure?' value="Delete Image" type="submit" />
#      <input name="authenticity_token" type="hidden" value="10f2163b45388899ad4d5ae948988266befcb6c3d1b2451cf657a0c293d605a6"/>
#    </form>"

<%= button_to('Destroy', 'http://www.example.com',
          method: "delete", remote: true, data: { confirm: 'Are you sure?', disable_with: 'loading...' }) %>
# => "<form class='button_to' method='post' action='http://www.example.com' data-remote='true'>
#       <input name='_method' value='delete' type='hidden' />
#       <input value='Destroy' type='submit' data-disable-with='loading...' data-confirm='Are you sure?' />
#       <input name="authenticity_token" type="hidden" value="10f2163b45388899ad4d5ae948988266befcb6c3d1b2451cf657a0c293d605a6"/>
#     </form>"
#

# File actionview/lib/action_view/helpers/url_helper.rb, line 543
def current_page?(options, check_parameters: false)
  unless request
    raise "You cannot use helpers that need to determine the current " \
          "page unless your view context provides a Request object " \
          "in a #request method"
  end

  return false unless request.get? || request.head?

  check_parameters ||= options.is_a?(Hash) && options.delete(:check_parameters)
  url_string = URI.parser.unescape(url_for(options)).force_encoding(Encoding::BINARY)

  # We ignore any extra parameters in the request_uri if the
  # submitted url doesn't have any either. This lets the function
  # work with things like ?order=asc
  # the behaviour can be disabled with check_parameters: true
  request_uri = url_string.index("?") || check_parameters ? request.fullpath : request.path
  request_uri = URI.parser.unescape(request_uri).force_encoding(Encoding::BINARY)

  if url_string.start_with?("/") && url_string != "/"
    url_string.chomp!("/")
    request_uri.chomp!("/")
  end

  if %r{^\w+://}.match?(url_string)
    url_string == "#{request.protocol}#{request.host_with_port}#{request_uri}"
  else
    url_string == request_uri
  end
end

True, если текущий URI запроса был сгенерирован заданным options.

Примеры

Предположим, мы находимся на странице с действием http://www.example.com/shop/checkout?order=desc&page=1.

current_page?(action: 'process')
# => false

current_page?(action: 'checkout')
# => true

current_page?(controller: 'library', action: 'checkout')
# => false

current_page?(controller: 'shop', action: 'checkout')
# => true

current_page?(controller: 'shop', action: 'checkout', order: 'asc')
# => false

current_page?(controller: 'shop', action: 'checkout', order: 'desc', page: '1')
# => true

current_page?(controller: 'shop', action: 'checkout', order: 'desc', page: '2')
# => false

current_page?('http://www.example.com/shop/checkout')
# => true

current_page?('http://www.example.com/shop/checkout', check_parameters: true)
# => false

current_page?('/shop/checkout')
# => true

current_page?('http://www.example.com/shop/checkout?order=desc&page=1')
# => true

Предположим, мы находимся на странице с действием http://www.example.com/products с методом POST в случае неверного продукта.

current_page?(controller: 'product', action: 'index')
# => false

Мы также можем передавать символьные аргументы вместо строк.

# File actionview/lib/action_view/helpers/url_helper.rb, line 196
def link_to(name = nil, options = nil, html_options = nil, &block)
  html_options, options, name = options, name, block if block_given?
  options ||= {}

  html_options = convert_options_to_data_attributes(options, html_options)

  url = url_for(options)
  html_options["href".freeze] ||= url

  content_tag("a".freeze, name || url, html_options, &block)
end

Создаёт элемент ссылки с указанным name, используя URL, созданный набором options. См. допустимые параметры в документации для url_for. Также можно передать строку вместо хэша опций, что создаёт ссылку, использующую значение строки в качестве значения href для ссылки. Использование :back символа вместо хэша опций создаст ссылку на referrer (если referrer не существует, будет использована ссылка JavaScript "назад"). Если nil передаётся как имя, то значение самой ссылки станет именем.

Подписи

link_to(body, url, html_options = {})
  # url is a String; you can use URL helpers like
  # posts_path

link_to(body, url_options = {}, html_options = {})
  # url_options, except :method, is passed to url_for

link_to(options = {}, html_options = {}) do
  # name
end

link_to(url, html_options = {}) do
  # name
end

Параметры

• :data - Этот параметр можно использовать для добавления пользовательских атрибутов данных.

• method: symbol of HTTP verb - Этот модификатор динамически создаст HTML-форму и немедленно отправит форму на обработку с использованием указанного HTTP-метода. Полезно для связей, выполняющих операцию POST в опасных действиях, таких как удаление записи (которые боты поиска могут следовать при сканировании вашего сайта). Поддерживаемые методы: :post, :delete, :patch, и :put. Обратите внимание, что если у пользователя отключён JavaScript, запрос вернётся к использованию GET. Если href: '#' используется, и у пользователя отключён JavaScript, нажатие на ссылку не повлияет. Если вы полагаетесь на поведение POST, вам нужно проверить его в действии контроллера, используя методы объекта запроса для post?, delete?, patch?, или put?.

• remote: true - Это позволит драйверу unobtrusive JavaScript выполнить AJAX-запрос к указанному URL вместо перехода по ссылке. Драйверы предоставляют механизмы для прослушивания завершения AJAX-запроса и выполнения операций JavaScript после их завершения.

Атрибуты данных

• confirm: 'question?' - Это позволит драйверу unobtrusive JavaScript задать вопрос, указанный (в данном случае результирующий текст будет question?). Если пользователь соглашается, ссылка обрабатывается обычно, в противном случае никаких действий не выполняется.

• :disable_with - Значение этого параметра будет использоваться как имя для отключенной версии ссылки. Эта функция предоставляется драйвером unobtrusive JavaScript.

Примеры

Поскольку он полагается на url_for, link_to поддерживает аргументы контроллера/действия/id старого стиля и новые RESTful маршруты. Текущий стиль Rails отдаёт предпочтение RESTful маршрутам, когда это возможно, поэтому базируйте своё приложение на ресурсах и используйте

link_to "Profile", profile_path(@profile)
# => <a href="/profiles/1">Profile</a>

или даже более краткое

link_to "Profile", @profile
# => <a href="/profiles/1">Profile</a>

вместо более длинного и громоздкого старого стиля, не ориентированного на ресурсы:

link_to "Profile", controller: "profiles", action: "show", id: @profile
# => <a href="/profiles/show/1">Profile</a>

Аналогично,

link_to "Profiles", profiles_path
# => <a href="/profiles">Profiles</a>

лучше, чем

link_to "Profiles", controller: "profiles"
# => <a href="/profiles">Profiles</a>

Когда имя равно nil, href отображается вместо него.

link_to nil, "http://example.com"
# => <a href="http://www.example.com">http://www.example.com</a>

Вы можете использовать блок, если целевой объект вашей ссылки трудно вписать в параметр имени. Пример ERB:

<%= link_to(@profile) do %>
  <strong><%= @profile.name %></strong> -- <span>Check it out!</span>
<% end %>
# => <a href="/profiles/1">
       <strong>David</strong> -- <span>Check it out!</span>
     </a>

Классы и идентификаторы для CSS легко создавать:

link_to "Articles", articles_path, id: "news", class: "article"
# => <a href="/articles" class="article" id="news">Articles</a>

Будьте осторожны при использовании старого стиля аргументов, так как нужен дополнительный литеральный хэш:

link_to "Articles", { controller: "articles" }, id: "news", class: "article"
# => <a href="/articles" class="article" id="news">Articles</a>

Пропуск хэша приводит к неправильной ссылке:

link_to "WRONG!", controller: "articles", id: "news", class: "article"
# => <a href="/articles/index/news?class=article">WRONG!</a>

link_to также может создавать ссылки с якорями или строками запроса:

link_to "Comment wall", profile_path(@profile, anchor: "wall")
# => <a href="/profiles/1#wall">Comment wall</a>

link_to "Ruby on Rails search", controller: "searches", query: "ruby on rails"
# => <a href="/searches?query=ruby+on+rails">Ruby on Rails search</a>

link_to "Nonsense search", searches_path(foo: "bar", baz: "quux")
# => <a href="/searches?foo=bar&amp;baz=quux">Nonsense search</a>

Единственный параметр, специфичный для link_to (:method), используется следующим образом:

link_to("Destroy", "http://www.example.com", method: :delete)
# => <a href='http://www.example.com' rel="nofollow" data-method="delete">Destroy</a>

Вы также можете использовать пользовательские атрибуты данных с помощью параметра :data:

link_to "Visit Other Site", "http://www.rubyonrails.org/", data: { confirm: "Are you sure?" }
# => <a href="http://www.rubyonrails.org/" data-confirm="Are you sure?">Visit Other Site</a>

Также можно установить любые атрибуты ссылки, такие как target, rel, type:

link_to "External link", "http://www.rubyonrails.org/", target: "_blank", rel: "nofollow"
# => <a href="http://www.rubyonrails.org/" target="_blank" rel="nofollow">External link</a>

# File actionview/lib/action_view/helpers/url_helper.rb, line 432
def link_to_if(condition, name, options = {}, html_options = {}, &block)
  if condition
    link_to(name, options, html_options)
  else
    if block_given?
      block.arity <= 1 ? capture(name, &block) : capture(name, options, html_options, &block)
    else
      ERB::Util.html_escape(name)
    end
  end
end

Создаёт тег ссылки с указанным name, используя URL, созданный набором options если condition равно true, в противном случае возвращается только имя. Для настройки поведения по умолчанию вы можете передать блок, который принимает имя или полный список аргументов для link_to_unless (см. примеры в link_to_unless).

Примеры

<%= link_to_if(@current_user.nil?, "Login", { controller: "sessions", action: "new" }) %>
# If the user isn't logged in...
# => <a href="/sessions/new/">Login</a>

<%=
   link_to_if(@current_user.nil?, "Login", { controller: "sessions", action: "new" }) do
     link_to(@current_user.login, { controller: "accounts", action: "show", id: @current_user })
   end
%>
# If the user isn't logged in...
# => <a href="/sessions/new/">Login</a>
# If they are logged in...
# => <a href="/accounts/show/3">my_username</a>

# File actionview/lib/action_view/helpers/url_helper.rb, line 408
def link_to_unless(condition, name, options = {}, html_options = {}, &block)
  link_to_if !condition, name, options, html_options, &block
end

Создаёт тег ссылки с указанным name, используя URL, созданный набором options если condition не равно true, в противном случае возвращается только имя. Для настройки поведения по умолчанию (например, отобразить ссылку входа, а не просто текст ссылки) можно передать блок, принимающий имя или полный список аргументов для link_to_unless.

Примеры

<%= link_to_unless(@current_user.nil?, "Reply", { action: "reply" }) %>
# If the user is logged in...
# => <a href="/controller/reply/">Reply</a>

<%=
   link_to_unless(@current_user.nil?, "Reply", { action: "reply" }) do |name|
     link_to(name, { controller: "accounts", action: "signup" })
   end
%>
# If the user is logged in...
# => <a href="/controller/reply/">Reply</a>
# If not...
# => <a href="/accounts/signup">Reply</a>

# File actionview/lib/action_view/helpers/url_helper.rb, line 384
def link_to_unless_current(name, options = {}, html_options = {}, &block)
  link_to_unless current_page?(options), name, options, html_options, &block
end

Создаёт тег ссылки заданного name с помощью URL, созданного набором options, если текущий URI запроса не совпадает с ссылками, в противном случае возвращается только имя (или выводится блок, если он есть). Вы можете предоставить link_to_unless_current блок, который специализирует стандартное поведение (например, отображать ссылку «Начать здесь» вместо текста ссылки).

Примеры

Предположим, у вас есть навигационное меню…

<ul id="navbar">
  <li><%= link_to_unless_current("Home", { action: "index" }) %></li>
  <li><%= link_to_unless_current("About Us", { action: "about" }) %></li>
</ul>

Если в действии «о нас», он отобразит…

<ul id="navbar">
  <li><a href="/controller/index">Home</a></li>
  <li>About Us</li>
</ul>

…но если в действии «индекс», он отобразит:

<ul id="navbar">
  <li>Home</li>
  <li><a href="/controller/about">About Us</a></li>
</ul>

Встроенный блок, переданный link_to_unless_current оценивается, если текущее действие является заданным действием. Таким образом, если у нас есть страница комментариев и мы хотим отобразить ссылку «Вернуться назад» вместо ссылки на страницу комментариев, мы можем сделать что-то вроде этого…

<%=
    link_to_unless_current("Comment", { controller: "comments", action: "new" }) do
       link_to("Go back", { controller: "posts", action: "index" })
    end
 %>

# File actionview/lib/action_view/helpers/url_helper.rb, line 482
def mail_to(email_address, name = nil, html_options = {}, &block)
  html_options, name = name, nil if block_given?
  html_options = (html_options || {}).stringify_keys

  extras = %w{ cc bcc body subject reply_to }.map! { |item|
    option = html_options.delete(item).presence || next
    "#{item.dasherize}=#{ERB::Util.url_encode(option)}"
  }.compact
  extras = extras.empty? ? "".freeze : "?" + extras.join("&")

  encoded_email_address = ERB::Util.url_encode(email_address).gsub("%40", "@")
  html_options["href"] = "mailto:#{encoded_email_address}#{extras}"

  content_tag("a".freeze, name || email_address, html_options, &block)
end

Создаёт тег ссылки mailto по указанному email_address, который также используется в качестве имени ссылки, если name не указан. Дополнительные атрибуты HTML для ссылки можно передать в html_options.

mail_to имеет несколько методов для настройки самого письма, передавая специальные ключи в html_options.

Параметры

• :subject - Установка темы письма.

• :body - Установка тела письма.

• :cc - Добавление дополнительных получателей в качестве копий.

• :bcc - Добавление дополнительных получателей в качестве скрытых копий.

• :reply_to - Установка поля Ответ на для письма.

Защита

До Rails 4.0, mail_to предоставлял варианты кодирования адреса, чтобы затруднить сборщик электронных писем. Чтобы воспользоваться этими вариантами, установите actionview-encoded_mail_to gem.

Примеры

mail_to "me@domain.com"
# => <a href="mailto:me@domain.com">me@domain.com</a>

mail_to "me@domain.com", "My email"
# => <a href="mailto:me@domain.com">My email</a>

mail_to "me@domain.com", "My email", cc: "ccaddress@domain.com",
         subject: "This is an example email"
# => <a href="mailto:me@domain.com?cc=ccaddress@domain.com&subject=This%20is%20an%20example%20email">My email</a>

Вы также можете использовать блок, если ссылка-цель сложно уместить в параметр имени. ERB пример:

<%= mail_to "me@domain.com" do %>
  <strong>Email me:</strong> <span>me@domain.com</span>
<% end %>
# => <a href="mailto:me@domain.com">
       <strong>Email me:</strong> <span>me@domain.com</span>
     </a>