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

# File actionview/lib/action_view/helpers/url_helper.rb, line 279
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
  convert_boolean_attributes!(html_options, %w(disabled))

  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) : ''.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.merge!(method: form_method, action: url)
  form_options.merge!("data-remote" => "true") if remote

  request_token_tag = form_method == 'post' ? token_tag : ''

  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
    params.each do |param_name, value|
      inner_tags.safe_concat tag(:input, type: "hidden", name: param_name, value: value.to_param)
    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, позволит драйверам Unobtrusive 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 526
def current_page?(options)
  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?

  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
  request_uri = url_string.index("?") ? request.fullpath : request.path
  request_uri = URI.parser.unescape(request_uri).force_encoding(Encoding::BINARY)

  if url_string =~ /^\w+:\/\//
    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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

# File actionview/lib/action_view/helpers/url_helper.rb, line 175
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'] ||= url

  content_tag(:a, name || url, html_options, &block)
end

Создаёт тег ссылки с заданным name, используя URL, созданный набором options. См. допустимые параметры в документации для url_for. Также можно передать строку вместо хеша параметров, что сгенерирует тег ссылки, использующий значение строки как значение атрибута href для ссылки. Использование :back символа вместо хеша параметров сгенерирует ссылку на страницу-источник (будет использована ссылка 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>

Вы можете использовать блок, если ваша ссылка-цель трудно вписывается в параметр name. Пример с 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>

# File actionview/lib/action_view/helpers/url_helper.rb, line 407
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 383
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 359
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>

…но если вы находитесь на главной странице («index»), будет отображено:

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

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

<%=
    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 456
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 }.map! { |item|
    option = html_options.delete(item) || next
    "#{item}=#{Rack::Utils.escape_path(option)}"
  }.compact
  extras = extras.empty? ? '' : '?' + extras.join('&')

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

  content_tag(:a, name || email_address, html_options, &block)
end

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

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

Параметры

• :subject — Задаёт тему электронного письма.

• :body — Задаёт тело электронного письма.

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

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

Защита

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

Примеры

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>