Simple Form Nested Fields

Nested fields helper for simple_form.

Makes it easier to handle forms with referenced/embedded models and attributes; e.g. a document with embedded texts, a project with referenced tasks, or an invoice with line items.

Works with standard Rails forms and SimpleForm.

This gem depends on jQuery.

Add this line to your application's Gemfile:

gem 'simple_form_nested_fields'

And then execute:

$ bundle

Or install it yourself as:

$ gem install simple_form_nested_fields

If using sprockets, require the javascript in your application.js:

//= require simple_form_nested_fields

and initialise the plugin like this:

$(document).ready(
  function() {
    $(".simple_form_nested_fields").SimpleFormNestedFields()
  }
)

Suppose you have a model MyDoc, which embeds texts:

# app/models/my_doc.rb
class MyDoc
  include Mongoid::Document
  embeds_many :texts, class_name: 'Text'
  accepts_nested_attributes_for :texts, allow_destroy: true
end

# app/models/text.rb
class Text
  include Mongoid::Document
  field :body, type: String
  embedded_in :my_doc, class_name: 'MyDoc'
end

You can then use the nested_fields_for helper to work with the texts in your form:

= simple_form_for @my_doc do |f|
  = f.nested_fields_for :texts
  = f.submit

This will render the texts/_fields partial, in which you can use the fields helper:

// app/views/my_docs/texts/_fields.html.slim
= fields.input :body

Subclassing of the relation class is handled automatically by default with:

• partials corresponding to each subclass
• select input next to the add link that allows the user choose the subclass to be added

The choice of classes can be configured as follows:

= f.nested_fields_for :variants, nil, item_classes: [MyDoc::Variant::One, MyDoc::Variant::Two]

Making the nested fields sortable is straight forward.

Using our MyDoc and texts example, the models would look like this (note the order on the embeds_many and the position field on the Text):

# app/models/my_doc.rb
class MyDoc
  include Mongoid::Document
  embeds_many :texts, class_name: 'Text', order: :position.asc
  accepts_nested_attributes_for :texts, allow_destroy: true
end

# app/models/text.rb
class Text
  include Mongoid::Document
  field :body, type: String
  field :position, type: Integer
  embedded_in :my_doc, class_name: 'MyDoc'
end

Then in your MyDoc form simply pass the sortable option to the nested_fields_for helper (note that in order to pass the option parameter, you have to pass the second parameter: the collection/record object):

= simple_form_for @my_doc do |f|
  = f.nested_fields_for :texts, @my_doc.texts, sortable: true
  = f.submit

Please note the position input is automatically added to the partial.

You can override the default _fields partial lookup path as follows:

= simple_form_for @my_doc do |f|
  = f.nested_fields_for :texts, nil, partial: 'my/own/path/to/fields'
  = f.submit

You can change the text on the add and remove links by overriding the locale file:

# config/locales/simple_form_nested_fields.en.yml
en:
  simple_form_nested_fields:
    links:
      add: 'Add %{model_name}'
      remove: 'Remove'

The gem has no default styling, but leaves that up to you. For reference, here's an example markup:

<div class="simple_form_nested_fields simple_form_nested_fields--texts">
  <div class="simple_form_nested_fields__title">Texts</div>
  <div class="simple_form_nested_fields__items">
    <div class="simple_form_nested_fields__item simple_form_nested_fields__item--new">
      <!-- fields -->
      <a class="simple_form_nested_fields__link simple_form_nested_fields__link--remove">Remove</a>
    </div>
  </div>
  <div class="simple_form_nested_fields__links">
    <a class="simple_form_nested_fields__link simple_form_nested_fields__link--add">Add Title</a>
  </div>
</div>

• Sortable field name should be configurable (position by default)

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Bug reports and pull requests are welcome on GitHub at https://github.com/tomasc/simple_form_nested_fields. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

The gem is available as open source under the terms of the MIT License.