Formtastic::Helpers::InputsHelper#inputs

Parsed documentation:
View on GitHub
{#inputs} creates an input fieldset and ol tag wrapping for use around a set of inputs.  It can be
called either with a block (in which you can do the usual Rails form stuff, HTML, ERB, etc),
or with a list of fields (accepting all default arguments and options). These two examples
are functionally equivalent:

    # With a block:
    <% semantic_form_for @post do |form| %>
      <% f.inputs do %>
        <%= f.input :title %>
        <%= f.input :body %>
      <% end %>
    <% end %>

    # With a list of fields (short hand syntax):
    <% semantic_form_for @post do |form| %>
      <%= f.inputs :title, :body %>
    <% end %>

    # Output:
    <form ...>
      <fieldset class="inputs">
        <ol>
          <li class="string">...</li>
          <li class="text">...</li>
        </ol>
      </fieldset>
    </form>

**Quick Forms**

Quick, scaffolding-style forms can be easily rendered for rapid early development if called
without a block or a field list. In the case an input is rendered for **most** columns in
the model's database table (like Rails' scaffolding) plus inputs for some model associations.

In this case, all inputs are rendered with default options and arguments. You'll want more
control than this in a production application, but it's a great way to get started, then
come back later to customise the form with a field list or a block of inputs.  Example:

    <% semantic_form_for @post do |form| %>
      <%= f.inputs %>
    <% end %>

**Nested Attributes**

One of the most complicated parts of Rails forms comes when nesting the inputs for
attrinbutes on associated models. Formtastic can take the pain away for many (but not all)
situations.

Given the following models:

    # Models
    class User < ActiveRecord::Base
      has_one :profile
      accepts_nested_attributes_for :profile
    end
    class Profile < ActiveRecord::Base
      belongs_to :user
    end

Formtastic provides a helper called `semantic_fields_for`, which wraps around Rails' built-in
`fields_for` helper for backwards compatibility with previous versions of Formtastic, and for
a consistent method naming API. The following examples are functionally equivalent:

    <% semantic_form_for @user do |form| %>
      <%= f.inputs :name, :email %>

      <% f.semantic_fields_for :profile do |profile| %>
        <% profile.inputs do %>
          <%= profile.input :biography %>
          <%= profile.input :twitter_name %>
        <% end %>
      <% end %>
    <% end %>

    <% semantic_form_for @user do |form| %>
      <%= f.inputs :name, :email %>

      <% f.fields_for :profile do |profile| %>
        <% profile.inputs do %>
          <%= profile.input :biography %>
          <%= profile.input :twitter_name %>
        <% end %>
      <% end %>
    <% end %>

{#inputs} also provides a DSL similar to `fields_for` / `semantic_fields_for` to reduce the
lines of code a little:

    <% semantic_form_for @user do |f| %>
      <%= f.inputs :name, :email %>

      <% f.inputs :for => :profile do %>
        <%= profile.input :biography %>
        <%= profile.input :twitter_name %>
        <%= profile.input :shoe_size %>
      <% end %>
    <% end %>

The `:for` option also works with short hand syntax:

    <% semantic_form_for @post do |form| %>
      <%= f.inputs :name, :email %>
      <%= f.inputs :biography, :twitter_name, :shoe_size, :for => :profile %>
    <% end %>

{#inputs} will always create a new `<fieldset>` wrapping, so only use it when it makes sense
in the document structure and semantics (using `semantic_fields_for` otherwise).

All options except `:name`, `:title` and `:for` will be passed down to the fieldset as HTML
attributes (id, class, style, etc).

When nesting `inputs()` inside another `inputs()` block, the nested content will
automatically be wrapped in an `<li>` tag to preserve the HTML validity (a `<fieldset>`
cannot be a direct descendant of an `<ol>`.


@option *args :for [Symbol, ActiveModel, Array]
  The contents of this option is passed down to Rails' fields_for() helper, so it accepts the same values.

@option *args :name [String]
  The optional name passed into the `<legend>` tag within the fieldset (alias of `:title`)

@option *args :title [String]
  The optional name passed into the `<legend>` tag within the fieldset (alias of `:name`)


@example Quick form: Render a scaffold-like set of inputs for automatically guessed attributes and simple associations on the model, with all default arguments and options
  <% semantic_form_for @post do |form| %>
    <%= f.inputs %>
  <% end %>

@example Quick form: Skip one or more fields
  <%= f.inputs :except => [:featured, :something_for_admin_only] %>
  <%= f.inputs :except => :featured %>

@example Short hand: Render inputs for a named set of attributes and simple associations on the model, with all default arguments and options
  <% semantic_form_for @post do |form| %>
    <%= f.inputs :title, :body, :user, :categories %>
  <% end %>

@example Block: Render inputs for attributes and simple associations with full control over arguments and options
  <% semantic_form_for @post do |form| %>
    <%= f.inputs do %>
      <%= f.input :title ... %>
      <%= f.input :body ... %>
      <%= f.input :user ... %>
      <%= f.input :categories ... %>
    <% end %>
  <% end %>

@example Multiple blocks: Render inputs in multiple fieldsets
  <% semantic_form_for @post do |form| %>
    <%= f.inputs do %>
      <%= f.input :title ... %>
      <%= f.input :body ... %>
    <% end %>
    <%= f.inputs do %>
      <%= f.input :user ... %>
      <%= f.input :categories ... %>
    <% end %>
  <% end %>

@example Provide text for the `<legend>` to name a fieldset (with a block)
  <% semantic_form_for @post do |form| %>
    <%= f.inputs :name => 'Write something:' do %>
      <%= f.input :title ... %>
      <%= f.input :body ... %>
    <% end %>
    <%= f.inputs do :name => 'Advanced options:' do %>
      <%= f.input :user ... %>
      <%= f.input :categories ... %>
    <% end %>
  <% end %>

@example Provide text for the `<legend>` to name a fieldset (with short hand)
  <% semantic_form_for @post do |form| %>
    <%= f.inputs :title, :body, :name => 'Write something:'%>
    <%= f.inputs :user, :cateogies, :name => 'Advanced options:' %>
  <% end %>

@example Inputs for nested attributes (don't forget `accepts_nested_attributes_for` in your model, see Rails' `fields_for` documentation)
  <% semantic_form_for @user do |form| %>
    <%= f.inputs do %>
      <%= f.input :name ... %>
      <%= f.input :email ... %>
    <% end %>
    <%= f.inputs :for => :profile do |profile| %>
      <%= profile.input :user ... %>
      <%= profile.input :categories ... %>
    <% end %>
  <% end %>

@example Inputs for nested record (don't forget `accepts_nested_attributes_for` in your model, see Rails' `fields_for` documentation)
  <% semantic_form_for @user do |form| %>
    <%= f.inputs do %>
      <%= f.input :name ... %>
      <%= f.input :email ... %>
    <% end %>
    <%= f.inputs :for => @user.profile do |profile| %>
      <%= profile.input :user ... %>
      <%= profile.input :categories ... %>
    <% end %>
  <% end %>

@example Inputs for nested record with a different name (don't forget `accepts_nested_attributes_for` in your model, see Rails' `fields_for` documentation)
  <% semantic_form_for @user do |form| %>
    <%= f.inputs do %>
      <%= f.input :name ... %>
      <%= f.input :email ... %>
    <% end %>
    <%= f.inputs :for => [:user_profile, @user.profile] do |profile| %>
      <%= profile.input :user ... %>
      <%= profile.input :categories ... %>
    <% end %>
  <% end %>

@example Nesting {#inputs} blocks requires an extra `<li>` tag for valid markup
  <% semantic_form_for @user do |form| %>
    <%= f.inputs do %>
      <%= f.input :name ... %>
      <%= f.input :email ... %>
      <li>
        <%= f.inputs :for => [:user_profile, @user.profile] do |profile| %>
          <%= profile.input :user ... %>
          <%= profile.input :categories ... %>
        <% end %>
      </li>
    <% end %>
  <% end %>
Suggestions:
Please help! Open an issue on GitHub if this assessment is incorrect.