класс ActionView::Helpers::FormBuilder

# File actionview/lib/action_view/helpers/form_helper.rb, line 1858
def button(value = nil, options = {}, &block)
  value, options = nil, value if value.is_a?(Hash)
  value ||= submit_default_value
  @template.button_tag(value, options, &block)
end

Добавляет кнопку отправки для данной формы. Если значение не указано, проверяется, является ли объект новым ресурсом, чтобы создать соответствующую метку:

<%= form_for @post do |f| %>
  <%= f.button %>
<% end %>

В примере выше, если @post — новая запись, будет использоваться метка «Создать пост», в противном случае — «Обновить пост».

Эти метки можно настроить с помощью I18n, в ключе helpers.submit (так же, как и helper submit) и принять %{model} в качестве интерполяции перевода:

en:
  helpers:
    submit:
      create: "Create a %{model}"
      update: "Confirm changes to %{model}"

Также ищет ключ, специфичный для данного объекта:

en:
  helpers:
    submit:
      post:
        create: "Add %{model}"

Примеры

button("Create a post")
# => <button name='button' type='submit'>Create post</button>

button do
  content_tag(:strong, 'Ask me!')
end
# => <button name='button' type='submit'>
#      <strong>Ask me!</strong>
#    </button>

# File actionview/lib/action_view/helpers/form_helper.rb, line 1709
def check_box(method, options = {}, checked_value = "1", unchecked_value = "0")
  @template.check_box(@object_name, method, objectify_options(options), checked_value, unchecked_value)
end

Возвращает тег checkbox, настроенный для доступа к указанному атрибуту (идентифицируемому по method) объекта, назначенного шаблону (идентифицируемому по object). Этот объект должен быть экземпляром объекта (@object), а не локальным объектом. Ожидается, что method вернёт целое число, и если это целое число больше нуля, то checkbox будет отмечен. Дополнительные параметры тега input могут быть переданы в виде хеша с options. Значение checked_value по умолчанию равно 1, а значение по умолчанию unchecked_value — 0, что удобно для булевых значений.

Особенности

Спецификация HTML говорит, что неотмеченные checkbox не отправляются, и поэтому веб-браузеры их не отправляют. К сожалению, это приводит к особенности: если у модели Invoice есть флаг paid, и в форме, редактирующей платную накладную, пользователь сбрасывает её checkbox, параметр paid не отправляется. Таким образом, любое выражение присвоения по массе, подобное

@invoice.update(params[:invoice])

не обновило бы флаг.

Чтобы предотвратить это, helper генерирует вспомогательное скрытое поле перед самим checkbox. Скрытое поле имеет то же имя, и его атрибуты имитируют неотмеченный checkbox.

Таким образом, клиент отправляет только скрытое поле (означающее, что checkbox не отмечен), или оба поля. Поскольку спецификация HTML гласит, что пары ключ/значение должны отправляться в том же порядке, в котором они появляются в форме, и извлечение параметров получает последнее вхождение любого повторяющегося ключа в строке запроса, это работает для обычных форм.

К сожалению, это решение не работает, когда checkbox находится внутри массивоподобного параметра, как в

<%= fields_for "project[invoice_attributes][]", invoice, index: nil do |form| %>
  <%= form.check_box :paid %>
  ...
<% end %>

потому что повторение имени параметра именно то, что Rails стремится различать элементы массива. Для каждого элемента с отмеченным checkbox вы получаете дополнительный «фантомный» элемент только с этим атрибутом, назначенным «0».

В этом случае предпочтительнее использовать check_box_tag или использовать хеши вместо массивов.

# Let's say that @post.validated? is 1:
check_box("post", "validated")
# => <input name="post[validated]" type="hidden" value="0" />
#    <input checked="checked" type="checkbox" id="post_validated" name="post[validated]" value="1" />

# Let's say that @puppy.gooddog is "no":
check_box("puppy", "gooddog", {}, "yes", "no")
# => <input name="puppy[gooddog]" type="hidden" value="no" />
#    <input type="checkbox" id="puppy_gooddog" name="puppy[gooddog]" value="yes" />

check_box("eula", "accepted", { class: 'eula_check' }, "yes", "no")
# => <input name="eula[accepted]" type="hidden" value="no" />
#    <input type="checkbox" class="eula_check" id="eula_accepted" name="eula[accepted]" value="yes" />

# File actionview/lib/action_view/helpers/form_options_helper.rb, line 824
def collection_check_boxes(method, collection, value_method, text_method, options = {}, html_options = {}, &block)
  @template.collection_check_boxes(@object_name, method, collection, value_method, text_method, objectify_options(options), @default_options.merge(html_options), &block)
end

Оборачивает ActionView::Helpers::FormOptionsHelper#collection_check_boxes для билдеров форм:

<%= form_for @post do |f| %>
  <%= f.collection_check_boxes :author_ids, Author.all, :id, :name_with_initial %>
  <%= f.submit %>
<% end %>

Для получения подробностей обратитесь к документации базового помощника.

# File actionview/lib/action_view/helpers/form_options_helper.rb, line 836
def collection_radio_buttons(method, collection, value_method, text_method, options = {}, html_options = {}, &block)
  @template.collection_radio_buttons(@object_name, method, collection, value_method, text_method, objectify_options(options), @default_options.merge(html_options), &block)
end

Оборачивает ActionView::Helpers::FormOptionsHelper#collection_radio_buttons для билдеров форм:

<%= form_for @post do |f| %>
  <%= f.collection_radio_buttons :author_id, Author.all, :id, :name_with_initial %>
  <%= f.submit %>
<% end %>

Для получения подробностей обратитесь к документации базового помощника.

# File actionview/lib/action_view/helpers/form_options_helper.rb, line 788
def collection_select(method, collection, value_method, text_method, options = {}, html_options = {})
  @template.collection_select(@object_name, method, collection, value_method, text_method, objectify_options(options), @default_options.merge(html_options))
end

Оборачивает ActionView::Helpers::FormOptionsHelper#collection_select для билдеров форм:

<%= form_for @post do |f| %>
  <%= f.collection_select :person_id, Author.all, :id, :name_with_initial, prompt: true %>
  <%= f.submit %>
<% end %>

Для получения подробностей обратитесь к документации базового помощника.

# File actionview/lib/action_view/helpers/date_helper.rb, line 1069
def date_select(method, options = {}, html_options = {})
  @template.date_select(@object_name, method, objectify_options(options), html_options)
end

Оборачивает ActionView::Helpers::DateHelper#date_select для билдеров форм:

<%= form_for @person do |f| %>
  <%= f.date_select :birth_date %>
  <%= f.submit %>
<% end %>

Для получения подробностей обратитесь к документации базового помощника.

# File actionview/lib/action_view/helpers/date_helper.rb, line 1093
def datetime_select(method, options = {}, html_options = {})
  @template.datetime_select(@object_name, method, objectify_options(options), html_options)
end

Оборачивает ActionView::Helpers::DateHelper#datetime_select для билдеров форм:

<%= form_for @person do |f| %>
  <%= f.datetime_select :last_request_at %>
  <%= f.submit %>
<% end %>

Для получения подробностей обратитесь к документации базового помощника.

# File actionview/lib/action_view/helpers/form_helper.rb, line 1573
def fields_for(record_name, record_object = nil, fields_options = {}, &block)
  fields_options, record_object = record_object, nil if record_object.is_a?(Hash) && record_object.extractable_options?
  fields_options[:builder] ||= options[:builder]
  fields_options[:namespace] = options[:namespace]
  fields_options[:parent_builder] = self

  case record_name
  when String, Symbol
    if nested_attributes_association?(record_name)
      return fields_for_with_nested_attributes(record_name, record_object, fields_options, block)
    end
  else
    record_object = record_name.is_a?(Array) ? record_name.last : record_name
    record_name   = model_name_from_record_or_class(record_object).param_key
  end

  index = if options.has_key?(:index)
    options[:index]
  elsif defined?(@auto_index)
    self.object_name = @object_name.to_s.sub(/\[\]$/,"")
    @auto_index
  end

  record_name = index ? "#{object_name}[#{index}][#{record_name}]" : "#{object_name}[#{record_name}]"
  fields_options[:child_index] = index

  @template.fields_for(record_name, record_object, fields_options, &block)
end

Создаёт область действия вокруг конкретного объекта модели, подобно form_for, но не создаёт сами теги формы. Это делает #fields_for подходящим для указания дополнительных объектов модели в той же форме.

Хотя использование и назначение fields_for аналогично form_for, его сигнатура метода немного отличается. Как и form_for, он передаёт объект FormBuilder, связанный с определённым объектом модели, в блок, и внутри блока можно вызывать методы билдера для генерации полей, связанных с объектом модели. Поля могут отражать объект модели двумя способами — как они названы (отсюда, как представленные значения отображаются в params хэше в контроллере) и какие значения по умолчанию отображаются при первом отображении формы, содержащей поля. Для того, чтобы оба этих свойства можно было указывать независимо, методу можно отдельно передать и имя объекта (представленное символом или строкой), и сам объект —

<%= form_for @person do |person_form| %>
  First name: <%= person_form.text_field :first_name %>
  Last name : <%= person_form.text_field :last_name %>

  <%= fields_for :permission, @person.permission do |permission_fields| %>
    Admin?  : <%= permission_fields.check_box :admin %>
  <% end %>

  <%= person_form.submit %>
<% end %>

В этом случае поле флажка будет представлено тегом HTML input с атрибутом name permission[admin], а переданное значение будет отображаться в контроллере как params[:permission][:admin]. Если @person.permission — это существующий запись с атрибутом admin, начальное состояние флажка при первом отображении будет отражать значение @person.permission.admin.

Часто это можно упростить, передав только имя объекта модели в fields_for —

<%= fields_for :permission do |permission_fields| %>
  Admin?: <%= permission_fields.check_box :admin %>
<% end %>

…в этом случае, если :permission также является именем переменной экземпляра @permission, начальное состояние поля ввода будет отражать значение атрибута этой переменной @permission.admin.

В качестве альтернативы можно передать только сам объект модели (если первый аргумент не является строкой или символом, fields_for поймёт, что имя опущено) —

<%= fields_for @person.permission do |permission_fields| %>
  Admin?: <%= permission_fields.check_box :admin %>
<% end %>

и fields_for получит необходимое имя поля из класса объекта модели, например, если @person.permission, принадлежит классу Permission, поле всё равно будет названо permission[admin].

Примечание: Это также работает для методов в FormOptionHelper и DateHelper, которые предназначены для работы с объектом в качестве основы, таких как FormOptionHelper#collection_select и ActionView::Helpers::DateHelper#datetime_select.

Примеры вложенных атрибутов

Когда объект, принадлежащий текущей области видимости, имеет метод записи вложенного атрибута для определённого атрибута, #fields_for создаст новую область видимости для этого атрибута. Это позволяет создавать формы, которые одновременно устанавливают или изменяют атрибуты родительского объекта и его ассоциаций.

Методы записи вложенных атрибутов — это обычные методы установщиков, названные в соответствии с ассоциацией. Наиболее распространённый способ определения этих установщиков — это использование accepts_nested_attributes_for в определении модели или определение метода с соответствующим именем. Например: метод установщика для ассоциации :address называется address_attributes=.

То, будет ли выдан билдер формы стиля «один к одному» или «один ко многим», зависит от того, возвращает ли обычный метод чтения один объект или массив объектов.

Один к одному

Рассмотрим класс Person, который возвращает один Address из метода чтения address и отвечает на метод записи address_attributes=:

class Person
  def address
    @address
  end

  def address_attributes=(attributes)
    # Process the attributes hash
  end
end

Теперь эту модель можно использовать с вложенным #fields_for, например так:

<%= form_for @person do |person_form| %>
  ...
  <%= person_form.fields_for :address do |address_fields| %>
    Street  : <%= address_fields.text_field :street %>
    Zip code: <%= address_fields.text_field :zip_code %>
  <% end %>
  ...
<% end %>

Если address уже является ассоциацией в Person, вы можете использовать accepts_nested_attributes_for для определения метода записи за вас:

class Person < ActiveRecord::Base
  has_one :address
  accepts_nested_attributes_for :address
end

Если вы хотите уничтожить связанную модель через форму, сначала нужно включить это с помощью параметра :allow_destroy для accepts_nested_attributes_for:

class Person < ActiveRecord::Base
  has_one :address
  accepts_nested_attributes_for :address, allow_destroy: true
end

Теперь, когда вы используете элемент формы с параметром _destroy со значением, которое вычисляется как true, вы уничтожите связанную модель (например, 1, '1', true или 'true'):

<%= form_for @person do |person_form| %>
  ...
  <%= person_form.fields_for :address do |address_fields| %>
    ...
    Delete: <%= address_fields.check_box :_destroy %>
  <% end %>
  ...
<% end %>

Один ко многим

Рассмотрим класс Person, который возвращает массив экземпляров Project из метода чтения projects и отвечает на метод записи projects_attributes=:

class Person
  def projects
    [@project1, @project2]
  end

  def projects_attributes=(attributes)
    # Process the attributes hash
  end
end

Обратите внимание, что метод записи projects_attributes= фактически необходим для #fields_for, чтобы правильно идентифицировать :projects как коллекцию, и для установки правильных индексов в разметке формы.

Если projects уже является ассоциацией в Person, вы можете использовать accepts_nested_attributes_for для определения метода записи за вас:

class Person < ActiveRecord::Base
  has_many :projects
  accepts_nested_attributes_for :projects
end

Теперь эту модель можно использовать с вложенным fields_for. Блок, переданный вложенному вызову #fields_for, будет повторяться для каждого экземпляра в коллекции:

<%= form_for @person do |person_form| %>
  ...
  <%= person_form.fields_for :projects do |project_fields| %>
    <% if project_fields.object.active? %>
      Name: <%= project_fields.text_field :name %>
    <% end %>
  <% end %>
  ...
<% end %>

Также можно указать используемый экземпляр:

<%= form_for @person do |person_form| %>
  ...
  <% @person.projects.each do |project| %>
    <% if project.active? %>
      <%= person_form.fields_for :projects, project do |project_fields| %>
        Name: <%= project_fields.text_field :name %>
      <% end %>
    <% end %>
  <% end %>
  ...
<% end %>

Или использовать коллекцию:

<%= form_for @person do |person_form| %>
  ...
  <%= person_form.fields_for :projects, @active_projects do |project_fields| %>
    Name: <%= project_fields.text_field :name %>
  <% end %>
  ...
<% end %>

Если вы хотите уничтожить связанные модели через форму, сначала нужно включить это с помощью параметра :allow_destroy для accepts_nested_attributes_for:

class Person < ActiveRecord::Base
  has_many :projects
  accepts_nested_attributes_for :projects, allow_destroy: true
end

Это позволит указать, какие модели нужно уничтожить в хэше атрибутов, добавив элемент формы для параметра _destroy со значением, которое вычисляется как true (например, 1, '1', true или 'true'):

<%= form_for @person do |person_form| %>
  ...
  <%= person_form.fields_for :projects do |project_fields| %>
    Delete: <%= project_fields.check_box :_destroy %>
  <% end %>
  ...
<% end %>

При использовании коллекции вы, возможно, захотите узнать индекс каждого объекта в массиве. Для этой цели в объекте FormBuilder доступен метод index.

<%= form_for @person do |person_form| %>
  ...
  <%= person_form.fields_for :projects do |project_fields| %>
    Project #<%= project_fields.index %>
    ...
  <% end %>
  ...
<% end %>

Обратите внимание, что #fields_for автоматически сгенерирует скрытое поле для хранения идентификатора записи. В некоторых случаях это скрытое поле не нужно, и вы можете передать include_id: false для предотвращения автоматического рендеринга скрытого поля #fields_for.

# File actionview/lib/action_view/helpers/form_helper.rb, line 1782
def file_field(method, options = {})
  self.multipart = true
  @template.file_field(@object_name, method, objectify_options(options))
end

Возвращает тег ввода для загрузки файла, настроенный для доступа к указанному атрибуту (определяемому method) объекта, назначенного шаблону (определяемого object). Дополнительные параметры тега ввода могут быть переданы в виде хэша с options. Эти параметры будут добавлены в HTML в виде атрибутов HTML-элемента, как показано в примере.

Использование этого метода внутри блока form_for установит кодировку обрамляющей формы в multipart/form-data.

Параметры

• Создаёт стандартные атрибуты HTML для тега.

• :disabled — если установлено в true, пользователь не сможет использовать этот элемент ввода.

• :multiple — если установлено в true, в большинстве современных браузеров пользователь сможет выбрать несколько файлов.

• :accept — если установлено в один или несколько MIME-типов, пользователю будет предложен фильтр при выборе файла. Вам всё равно нужно настроить валидации модели.

Примеры

file_field(:user, :avatar)
# => <input type="file" id="user_avatar" name="user[avatar]" />

file_field(:post, :image, :multiple => true)
# => <input type="file" id="post_image" name="post[image]" multiple="true" />

file_field(:post, :attached, accept: 'text/html')
# => <input accept="text/html" type="file" id="post_attached" name="post[attached]" />

file_field(:post, :image, accept: 'image/png,image/gif,image/jpeg')
# => <input type="file" id="post_image" name="post[image]" accept="image/png,image/gif,image/jpeg" />

file_field(:attachment, :file, class: 'file_input')
# => <input type="file" id="attachment_file" name="attachment[file]" class="file_input" />

# File actionview/lib/action_view/helpers/form_options_helper.rb, line 800
def grouped_collection_select(method, collection, group_method, group_label_method, option_key_method, option_value_method, options = {}, html_options = {})
  @template.grouped_collection_select(@object_name, method, collection, group_method, group_label_method, option_key_method, option_value_method, objectify_options(options), @default_options.merge(html_options))
end

Оборачивает ActionView::Helpers::FormOptionsHelper#grouped_collection_select для билдеров форм:

<%= form_for @city do |f| %>
  <%= f.grouped_collection_select :country_id, @continents, :countries, :name, :id, :name %>
  <%= f.submit %>
<% end %>

Для получения подробной информации обратитесь к документации базового помощника.

# File actionview/lib/action_view/helpers/form_helper.rb, line 1749
def hidden_field(method, options = {})
  @emitted_hidden_id = true if method == :id
  @template.hidden_field(@object_name, method, objectify_options(options))
end

Возвращает тег скрытого поля ввода, настроенный для доступа к указанному атрибуту (определяемому method) объекта, назначенного шаблону (определяемому object). Дополнительные параметры тега ввода могут быть переданы в виде хэша с options. Эти параметры будут добавлены в HTML в виде атрибутов HTML-элемента, как показано в примере.

Примеры

hidden_field(:signup, :pass_confirm)
# => <input type="hidden" id="signup_pass_confirm" name="signup[pass_confirm]" value="#{@signup.pass_confirm}" />

hidden_field(:post, :tag_list)
# => <input type="hidden" id="post_tag_list" name="post[tag_list]" value="#{@post.tag_list}" />

hidden_field(:user, :token)
# => <input type="hidden" id="user_token" name="user[token]" value="#{@user.token}" />

# File actionview/lib/action_view/helpers/form_helper.rb, line 1649
def label(method, text = nil, options = {}, &block)
  @template.label(@object_name, method, text, objectify_options(options), &block)
end

Возвращает тег метки, настроенный для маркировки поля ввода для указанного атрибута (идентифицированного по method) объекта, назначенного шаблону (идентифицированного по object). Текст метки по умолчанию соответствует имени атрибута, если только не найдена соответствующая локализация в текущем локализованном пакете I18n (через helpers.label.<modelname>.<attribute>) или не указан явно. Дополнительные параметры тега метки могут быть переданы как хеш options. Эти параметры будут добавлены в HTML-атрибуты элемента HTML, как показано в примере, за исключением параметра :value, который предназначен для настройки меток для тегов #radio_button (где значение используется в идентификаторе тега ввода).

Примеры

label(:post, :title)
# => <label for="post_title">Title</label>

Вы можете локализовать свои метки на основе модели и имени атрибута. Например, вы можете определить следующее в своем локализованном пакете (например, en.yml)

helpers:
  label:
    post:
      body: "Write your entire text here"

Что затем приведет к

label(:post, :body)
# => <label for="post_body">Write your entire text here</label>

Локализация также может быть основана исключительно на переводе имени атрибута (если вы используете ActiveRecord):

activerecord:
  attributes:
    post:
      cost: "Total cost"

label(:post, :cost)
# => <label for="post_cost">Total cost</label>

label(:post, :title, "A short title")
# => <label for="post_title">A short title</label>

label(:post, :title, "A short title", class: "title_label")
# => <label for="post_title" class="title_label">A short title</label>

label(:post, :privacy, "Public Post", value: "public")
# => <label for="post_privacy_public">Public Post</label>

label(:post, :terms) do
  'Accept <a href="/terms">Terms</a>.'.html_safe
end

# File actionview/lib/action_view/helpers/form_helper.rb, line 1730
def radio_button(method, tag_value, options = {})
  @template.radio_button(@object_name, method, tag_value, objectify_options(options))
end

Возвращает тег радиокнопки для доступа к указанному атрибуту (идентифицированному по method) объекта, назначенного шаблону (идентифицированному по object). Если текущее значение method равно tag_value, радиокнопка будет отмечена.

Чтобы принудительно установить радиокнопку в отмеченное состояние, передайте checked: true в хеш options. Вы также можете передать HTML-параметры.

# Let's say that @post.category returns "rails":
radio_button("post", "category", "rails")
radio_button("post", "category", "java")
# => <input type="radio" id="post_category_rails" name="post[category]" value="rails" checked="checked" />
#    <input type="radio" id="post_category_java" name="post[category]" value="java" />

radio_button("user", "receive_newsletter", "yes")
radio_button("user", "receive_newsletter", "no")
# => <input type="radio" id="user_receive_newsletter_yes" name="user[receive_newsletter]" value="yes" />
#    <input type="radio" id="user_receive_newsletter_no" name="user[receive_newsletter]" value="no" checked="checked" />

# File actionview/lib/action_view/helpers/form_options_helper.rb, line 776
def select(method, choices = nil, options = {}, html_options = {}, &block)
  @template.select(@object_name, method, choices, objectify_options(options), @default_options.merge(html_options), &block)
end

Оборачивает ActionView::Helpers::FormOptionsHelper#select для генераторов форм:

<%= form_for @post do |f| %>
  <%= f.select :person_id, Person.all.collect { |p| [ p.name, p.id ] }, include_blank: true %>
  <%= f.submit %>
<% end %>

Для получения подробной информации см. документацию основного помощника.

# File actionview/lib/action_view/helpers/form_helper.rb, line 1814
def submit(value=nil, options={})
  value, options = nil, value if value.is_a?(Hash)
  value ||= submit_default_value
  @template.submit_tag(value, options)
end

Добавляет кнопку отправки для данной формы. Если значение не задано, проверяется, является ли объект новым ресурсом, чтобы создать соответствующую метку:

<%= form_for @post do |f| %>
  <%= f.submit %>
<% end %>

В приведенном выше примере, если @post — новый ресурс, в качестве метки кнопки отправки будет использоваться «Создать пост», в противном случае — «Обновить пост».

Эти метки можно настроить с помощью I18n, в разделе helpers.submit, принимающем %{model} в качестве интерполяции перевода:

en:
  helpers:
    submit:
      create: "Create a %{model}"
      update: "Confirm changes to %{model}"

Также ищется ключ, специфичный для данного объекта:

en:
  helpers:
    submit:
      post:
        create: "Add %{model}"

# File actionview/lib/action_view/helpers/date_helper.rb, line 1081
def time_select(method, options = {}, html_options = {})
  @template.time_select(@object_name, method, objectify_options(options), html_options)
end

Оборачивает ActionView::Helpers::DateHelper#time_select для генераторов форм:

<%= form_for @race do |f| %>
  <%= f.time_select :average_lap %>
  <%= f.submit %>
<% end %>

Для получения подробной информации см. документацию основного помощника.

# File actionview/lib/action_view/helpers/form_options_helper.rb, line 812
def time_zone_select(method, priority_zones = nil, options = {}, html_options = {})
  @template.time_zone_select(@object_name, method, priority_zones, objectify_options(options), @default_options.merge(html_options))
end

Оборачивает ActionView::Helpers::FormOptionsHelper#time_zone_select для генераторов форм:

<%= form_for @user do |f| %>
  <%= f.time_zone_select :time_zone, nil, include_blank: true %>
  <%= f.submit %>
<% end %>

Для получения подробной информации см. документацию основного помощника.