base on Rails plugin to conveniently handle multiple models in a single form. # Unmaintained The Nested Form gem is **no longer maintained**. Feel free to fork this project. # Nested Form [<img src="https://secure.travis-ci.org/ryanb/nested_form.png?branch=master" alt="Build Status" />](http://travis-ci.org/ryanb/nested_form) This is a Rails gem for conveniently manage multiple nested models in a single form. It does so in an unobtrusive way through jQuery or Prototype. This gem only works with Rails 3. See the [rails2 branch](https://github.com/ryanb/nested_form/tree/rails2) for a plugin to work in Rails 2. An example project showing how this works is available in the [complex-nested-forms/nested_form branch](https://github.com/ryanb/complex-form-examples/tree/nested_form). ## Setup Add it to your Gemfile then run `bundle` to install it. ```ruby gem "nested_form" ``` And then add it to the Asset Pipeline in the application.js file: ``` //= require jquery_nested_form ``` ### Non Asset Pipeline Setup If you do not use the asset pipeline, run this generator to create the JavaScript file. ``` rails g nested_form:install ``` You can then include the generated JavaScript in your layout. ```erb <%= javascript_include_tag :defaults, "nested_form" %> ``` ## Usage Imagine you have a `Project` model that `has_many :tasks`. To be able to use this gem, you'll need to add `accepts_nested_attributes_for :tasks` to your Project model. If you wish to allow the nested objects to be destroyed, then add the `:allow_destroy => true` option to that declaration. See the [accepts_nested_attributes_for documentation](http://api.rubyonrails.org/classes/ActiveRecord/NestedAttributes/ClassMethods.html#method-i-accepts_nested_attributes_for) for details on all available options. This will create a `tasks_attributes=` method, so you may need to add it to the `attr_accessible` array (`attr_accessible :tasks_attributes`). Then use the `nested_form_for` helper method to enable the nesting. ```erb <%= nested_form_for @project do |f| %> ``` You will then be able to use `link_to_add` and `link_to_remove` helper methods on the form builder in combination with fields_for to dynamically add/remove nested records. ```erb <%= f.fields_for :tasks do |task_form| %> <%= task_form.text_field :name %> <%= task_form.link_to_remove "Remove this task" %> <% end %> <p><%= f.link_to_add "Add a task", :tasks %></p> ``` In order to choose how to handle, after validation errors, fields that are marked for destruction, the `marked_for_destruction` class is added on the div if the object is marked for destruction. ## Strong Parameters For Rails 4 or people using the "strong_parameters" gem, here is an example: ```ruby params.require(:project).permit(:name, tasks_attributes: [:id, :name, :_destroy]) ``` The `:id` is to make sure you do not end up with a whole lot of tasks. The `:_destroy` must be there so that we can delete tasks. ## SimpleForm and Formtastic Support Use `simple_nested_form_for` or `semantic_nested_form_for` for SimpleForm and Formtastic support respectively. ## Partials It is often desirable to move the nested fields into a partial to keep things organized. If you don't supply a block to fields_for it will look for a partial and use that. ```erb <%= f.fields_for :tasks %> ``` In this case it will look for a partial called "task_fields" and pass the form builder as an `f` variable to it. ## Specifying a Target for Nested Fields By default, `link_to_add` appends fields immediately before the link when clicked. This is not desirable when using a list or table, for example. In these situations, the "data-target" attribute can be used to specify where new fields should be inserted. ```erb <table id="tasks"> <%= f.fields_for :tasks, :wrapper => false do |task_form| %> <tr class="fields"> <td><%= task_form.text_field :name %></td> <td><%= task_form.link_to_remove "Remove this task" %></td> </tr> <% end %> </table> <p><%= f.link_to_add "Add a task", :tasks, :data => { :target => "#tasks" } %></p> ``` Note that the `:data` option above only works in Rails 3.1+. For Rails 3.0 and below, the following syntax must be used. ```erb <p><%= f.link_to_add "Add a task", :tasks, "data-target" => "#tasks" %></p> ``` ## JavaScript events Sometimes you want to do some additional work after element was added or removed, but only after DOM was _really_ modified. In this case simply listening for click events on 'Add new'/'Remove' link won't reliably work, because your code and code that inserts/removes nested field will run concurrently. This problem can be solved, because after adding or removing the field a set of custom events is triggered on this field. Using form example from above, if you click on the "Add a task" link, `nested:fieldAdded` and `nested:fieldAdded:tasks` will be triggered, while `nested:fieldRemoved` and `nested:fieldRemoved:tasks` will be triggered if you click "Remove this task" then. These events bubble up the DOM tree, going through `form` element, until they reach the `document`. This allows you to listen for the event and trigger some action accordingly. Field element, upon which action was made, is passed along with the `event` object. In jQuery you can access it via `event.field`, in Prototype the same field will be in `event.memo.field`. For example, you have a date input in a nested field and you want to use jQuery datepicker for it. This is a bit tricky, because you have to activate datepicker after field was inserted. ### jQuery ```javascript $(document).on('nested:fieldAdded', function(event){ // this field was just inserted into your form var field = event.field; // it's a jQuery object already! Now you can find date input var dateField = field.find('.date'); // and activate datepicker on it dateField.datepicker(); }) ``` ### Prototype ```javascript document.observe('nested:fieldAdded', function(event){ var field = event.memo.field; // it's already extended by Prototype var dateField = field.down('.date'); dateField.datepicker(); }) ``` Second type of event (i.e. `nested:fieldAdded:tasks`) is useful then you have more than one type of nested fields on a form (i.e. tasks and milestones) and want to distinguish, which exactly was added/deleted. See also [how to limit max count of nested fields](https://github.com/ryanb/nested_form/wiki/How-to:-limit-max-count-of-nested-fields) ## Enhanced jQuery JavaScript template You can override default behavior of inserting new subforms into your form. For example: ```javascript window.nestedFormEvents.insertFields = function(content, assoc, link) { return $(link).closest('form').find(assoc + '_fields').append($(content)); } ``` ## Contributing If you have any issues with Nested Form not addressed above or in the [example project](https://github.com/ryanb/complex-form-examples/tree/nested_form), please add an [issue on GitHub](https://github.com/ryanb/nested_form/issues) or [fork the project](https://help.github.com/articles/fork-a-repo) and send a [pull request](https://help.github.com/articles/using-pull-requests). To run the specs: ``` bundle install bundle exec rake spec:install bundle exec rake db:migrate bundle exec rake spec:all ``` See available rake tasks using `bundle exec rake -T`. ## Special Thanks This gem was originally based on the solution by Tim Riley in his [complex-form-examples fork](https://github.com/timriley/complex-form-examples/tree/unobtrusive-jquery-deep-fix2). Thank you Andrew Manshin for the Rails 3 transition, [Andrea Singh](https://github.com/madebydna) for converting to a gem and [Peter Giacomo Lombardo](https://github.com/pglombardo) for Prototype support. Andrea also wrote a great [blog post](http://blog.madebydna.com/all/code/2010/10/07/dynamic-nested-froms-with-the-nested-form-gem.html) on the internal workings of this gem. Thanks [Pavel Forkert](https://github.com/fxposter) for the SimpleForm and Formtastic support. ", Assign "at most 3 tags" to the expected json: {"id":"13052","tags":[]} "only from the tags list I provide: [{"id":77,"name":"3d"},{"id":89,"name":"agent"},{"id":17,"name":"ai"},{"id":54,"name":"algorithm"},{"id":24,"name":"api"},{"id":44,"name":"authentication"},{"id":3,"name":"aws"},{"id":27,"name":"backend"},{"id":60,"name":"benchmark"},{"id":72,"name":"best-practices"},{"id":39,"name":"bitcoin"},{"id":37,"name":"blockchain"},{"id":1,"name":"blog"},{"id":45,"name":"bundler"},{"id":58,"name":"cache"},{"id":21,"name":"chat"},{"id":49,"name":"cicd"},{"id":4,"name":"cli"},{"id":64,"name":"cloud-native"},{"id":48,"name":"cms"},{"id":61,"name":"compiler"},{"id":68,"name":"containerization"},{"id":92,"name":"crm"},{"id":34,"name":"data"},{"id":47,"name":"database"},{"id":8,"name":"declarative-gui "},{"id":9,"name":"deploy-tool"},{"id":53,"name":"desktop-app"},{"id":6,"name":"dev-exp-lib"},{"id":59,"name":"dev-tool"},{"id":13,"name":"ecommerce"},{"id":26,"name":"editor"},{"id":66,"name":"emulator"},{"id":62,"name":"filesystem"},{"id":80,"name":"finance"},{"id":15,"name":"firmware"},{"id":73,"name":"for-fun"},{"id":2,"name":"framework"},{"id":11,"name":"frontend"},{"id":22,"name":"game"},{"id":81,"name":"game-engine "},{"id":23,"name":"graphql"},{"id":84,"name":"gui"},{"id":91,"name":"http"},{"id":5,"name":"http-client"},{"id":51,"name":"iac"},{"id":30,"name":"ide"},{"id":78,"name":"iot"},{"id":40,"name":"json"},{"id":83,"name":"julian"},{"id":38,"name":"k8s"},{"id":31,"name":"language"},{"id":10,"name":"learning-resource"},{"id":33,"name":"lib"},{"id":41,"name":"linter"},{"id":28,"name":"lms"},{"id":16,"name":"logging"},{"id":76,"name":"low-code"},{"id":90,"name":"message-queue"},{"id":42,"name":"mobile-app"},{"id":18,"name":"monitoring"},{"id":36,"name":"networking"},{"id":7,"name":"node-version"},{"id":55,"name":"nosql"},{"id":57,"name":"observability"},{"id":46,"name":"orm"},{"id":52,"name":"os"},{"id":14,"name":"parser"},{"id":74,"name":"react"},{"id":82,"name":"real-time"},{"id":56,"name":"robot"},{"id":65,"name":"runtime"},{"id":32,"name":"sdk"},{"id":71,"name":"search"},{"id":63,"name":"secrets"},{"id":25,"name":"security"},{"id":85,"name":"server"},{"id":86,"name":"serverless"},{"id":70,"name":"storage"},{"id":75,"name":"system-design"},{"id":79,"name":"terminal"},{"id":29,"name":"testing"},{"id":12,"name":"ui"},{"id":50,"name":"ux"},{"id":88,"name":"video"},{"id":20,"name":"web-app"},{"id":35,"name":"web-server"},{"id":43,"name":"webassembly"},{"id":69,"name":"workflow"},{"id":87,"name":"yaml"}]" returns me the "expected json"