form_for

Creates a form and a scope around a specific model object that is used as a base for questioning about values for the fields.

  <% form_for :person, @person, :url => { :action => "update" } do |f| %>
    First name: <%= f.text_field :first_name %>
    Last name : <%= f.text_field :last_name %>
    Biography : <%= f.text_area :biography %>
    Admin?    : <%= f.check_box :admin %>
  <% end %>

Worth noting is that the form_for tag is called in a ERb evaluation block, not an ERb output block. So that’s <% %>, not <%= %>. Also worth noting is that form_for yields a form_builder object, in this example as f, which emulates the API for the stand-alone FormHelper methods, but without the object name. So instead of text_field :person, :name, you get away with f.text_field :name.

Even further, the form_for method allows you to more easily escape the instance variable convention. So while the stand-alone approach would require text_field :person, :name, :object => person to work with local variables instead of instance ones, the form_for calls remain the same. You simply declare once with :person, person and all subsequent field calls save :person and :object => person.

Also note that form_for doesn’t create an exclusive scope. It’s still possible to use both the stand-alone FormHelper methods and methods from FormTagHelper. For example:

  <% form_for :person, @person, :url => { :action => "update" } do |f| %>
    First name: <%= f.text_field :first_name %>
    Last name : <%= f.text_field :last_name %>
    Biography : <%= text_area :person, :biography %>
    Admin?    : <%= check_box_tag "person[admin]", @person.company.admin? %>
  <% end %>

Note: This also works for the methods in FormOptionHelper and DateHelper that are designed to work with an object as base, like FormOptionHelper#collection_select and DateHelper#datetime_select.

HTML attributes for the form tag can be given as :html => {…}. For example:

  <% form_for :person, @person, :html => {:id => 'person_form'} do |f| %>
    ...
  <% end %>

The above form will then have the id attribute with the value </tt>person_form</tt>, which you can then style with CSS or manipulate with JavaScript.

Relying on record identification

In addition to manually configuring the form_for call, you can also rely on record identification, which will use the conventions and named routes of that approach. Examples:

  <% form_for(@post) do |f| %>
    ...
  <% end %>

This will expand to be the same as:

  <% form_for :post, @post, :url => post_path(@post), :html => { :method => :put, :class => "edit_post", :id => "edit_post_45" } do |f| %>
    ...
  <% end %>

And for new records:

  <% form_for(Post.new) do |f| %>
    ...
  <% end %>

This will expand to be the same as:

  <% form_for :post, @post, :url => posts_path, :html => { :class => "new_post", :id => "new_post" } do |f| %>
    ...
  <% end %>

You can also overwrite the individual conventions, like this:

  <% form_for(@post, :url => super_post_path(@post)) do |f| %>
    ...
  <% end %>

And for namespaced routes, like admin_post_url:

  <% form_for([:admin, @post]) do |f| %>
   ...
  <% end %>

Customized form builders

You can also build forms using a customized FormBuilder class. Subclass <a href="/rails/ActionView/Helpers/FormBuilder">FormBuilder</a> and override or define some more helpers, then use your custom builder. For example, let’s say you made a helper to automatically add labels to form inputs.

  <% form_for :person, @person, :url => { :action => "update" }, :builder => LabellingFormBuilder do |f| %>
    <%= f.text_field :first_name %>
    <%= f.text_field :last_name %>
    <%= text_area :person, :biography %>
    <%= check_box_tag "person[admin]", @person.company.admin? %>
  <% end %>

In many cases you will want to wrap the above in another helper, so you could do something like the following:

  def labelled_form_for(name, object, options, &proc)
    form_for(name, object, options.merge(:builder => LabellingFormBuiler), &proc)
  end

If you don’t need to attach a form to a model instance, then check out FormTagHelper#form_tag.