No release in over 3 years
Low commit activity in last 3 years
Dynamically create and remove nested fields with simple_form
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Project Readme

Simple Form Nested Fields

Build Status Gem Version Coverage Status

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.

Dependencies

This gem depends on jQuery.

Installation

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()
  }
)

Usage

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

Inheritance

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]

Sortable

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.

Configuration

Custom partial path

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

I18n

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'

Styling

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>

Todo

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

Development

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.

Contributing

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.

License

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