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

Генерирует форму, содержащую единственную кнопку, которая отправляет запрос на 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 - Это будет использовать драйвер JavaScript для запроса с указанным вопросом. Если пользователь соглашается, ссылка обрабатывается обычно, в противном случае никаких действий не выполняется.

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

Примеры

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

<%= button_to "New", new_articles_path %>
# => "<form method="post" action="/articles/new" class="button_to">
#      <div><input value="New" type="submit" /></div>
#    </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">
#      <div>
#        <button type="submit">
#          Make happy <strong><%= @user.name %></strong>
#        </button>
#      </div>
#    </form>"

<%= button_to "New", { action: "new" }, form_class: "new-thing" %>
# => "<form method="post" action="/controller/new" class="new-thing">
#      <div><input value="New" type="submit" /></div>
#    </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">
#      <div>
#        <input value="Create" type="submit" />
#        <input name="authenticity_token" type="hidden" value="10f2163b45388899ad4d5ae948988266befcb6c3d1b2451cf657a0c293d605a6"/>
#      </div>
#    </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">
#      <div>
#        <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"/>
#      </div>
#    </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'>
#       <div>
#         <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"/>
#       </div>
#     </form>"
#

# File actionview/lib/action_view/helpers/url_helper.rb, line 287
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', content_tag('div', inner_tags), form_options)
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 534
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

Создаёт тег ссылки с заданным 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 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 если 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 423
def link_to_if(condition, name, options = {}, html_options = {}, &block)
  link_to_unless !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 391
def link_to_unless(condition, name, options = {}, html_options = {}, &block)
  if condition
    if block_given?
      block.arity <= 1 ? capture(name, &block) : capture(name, options, html_options, &block)
    else
      ERB::Util.html_escape(name)
    end
  else
    link_to(name, options, html_options)
  end
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 367
def link_to_unless_current(name, options = {}, html_options = {}, &block)
  link_to_unless current_page?(options), name, options, html_options, &block
end

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

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

Параметры

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

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

• :cc - Копировать дополнительные получателей в письмо.

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

Защита от спама

До 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>

# File actionview/lib/action_view/helpers/url_helper.rb, line 464
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? ? '' : '?' + ERB::Util.html_escape(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}".html_safe

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