cocoon

cocoon is a Rails3 gem to allow easier handling of nested forms.

Nested forms are forms that handle nested models and attributes in one form. For example a project with its tasks, an invoice with its ordered items.

It is formbuilder-agnostic, so it works with standard Rails, or Formtastic or simple_form.

Prerequisites

This gem uses jQuery, it is most useful to use this gem in a rails3 project where you are already using jQuery.

Furthermore i would advice you to use either formtastic or simple_form.

I have a sample project where I demonstrate the use of cocoon with formtastic.

Installation

Inside your Gemfile add the following:

gem "cocoon"

Rails 3.1

Add the following to application.js so it compiles to the asset_pipeline

//= require cocoon

Rails 3.x

If you are using Rails 3.0.x, you need to run the installation task (since rails 3.1 this is no longer needed):

rails g cocoon:install

This will install the needed javascript file. Inside your application.html.haml you will need to add below the default javascripts:

= javascript_include_tag :cocoon

or using erb, you write

<%= javascript_include_tag :cocoon %>

That is all you need to do to start using it!

Usage

Suppose you have a model Project:

rails g scaffold Project name:string description:string

and a project has many tasks:

rails g model Task description:string done:boolean project_id:integer

Edit the models to code the relation:

class Project < ActiveRecord::Base
  has_many :tasks
  accepts_nested_attributes_for :tasks, :reject_if => :all_blank, :allow_destroy => true
end

class Task < ActiveRecord::Base
  belongs_to :project
end

What we want to achieve is to get a form where we can add and remove the tasks dynamically. What we need for this, is that the fields for a new/existing task are defined in a partial view called _task_fields.html.

We will show the sample usage with the different possible form-builders.

Using formtastic

Inside our projects/_form partial we then write:

- f.inputs do
  = f.input :name
  = f.input :description
  %h3 Tasks
  #tasks
    = f.semantic_fields_for :tasks do |task|
      = render 'task_fields', :f => task
    .links
      = link_to_add_association 'add task', f, :tasks
  -f.buttons do
    = f.submit 'Save'

and inside the _task_fields partial we write:

.nested-fields
  = f.inputs do
    = f.input :description
    = f.input :done, :as => :boolean
    = link_to_remove_association "remove task", f

That is all there is to it!

There is an example project on github implementing it called formtastic-cocoon-demo.

Using simple_form

This is almost identical to formtastic, instead of writing semantic_fields_for you write simple_fields_for.

There is an example project on github implementing it called cocoon_simple_form_demo.

Using standard rails forms

I will provide a full example (and a sample project) later.

How it works

I define two helper functions:

link_to_add_association

This function will add a link to your markup that will, when clicked, dynamically add a new partial form for the given association. This should be placed below the semantic_fields_for.

It takes four parameters:

name: the text to show in the link
f: referring to the containing form-object
association: the name of the association (plural) of which a new instance needs to be added (symbol or string).
html_options: extra html-options (see link_to) There are three extra options that allow to control the placement of the new link-data:
- data-association-insertion-node : the jquery selector of the node
- data-association-insertion-method : jquery method that inserts the new data. before, after, append, prepend, etc. Default: before
- data-association-insertion-position : old method specifying where to insert new data.
  - this setting still works but data-association-insertion-method takes precedence. may be removed in a future version.

Optionally you could also leave out the name and supply a block that is captured to give the name (if you want to do something more complicated).

link_to_remove_association

This function will add a link to your markup that will, when clicked, dynamically remove the surrounding partial form. This should be placed inside the partial _<association-object-singular>_fields.

It takes three parameters:

name: the text to show in the link
f: referring to the containing form-object
html_options: extra html-options (see link_to)

Optionally you could also leave out the name and supply a block that is captured to give the name (if you want to do something more complicated).

Inside the html_options you can add an option :render_options, and the containing hash will be handed down to the form-builder for the inserted form. E.g. especially when using twitter-bootstrap and simple_form together, the simple_fields_for needs the option :wrapper => 'inline' which can be handed down as follows:

= link_to_add_association 'add something', f, :something, :render_options => {:wrapper => 'inline' }

Callbacks (upon insert and remove of items)

There is an option to add a callback on insertion or removal. If in your view you have the following snippet to select an owner (we use slim for demonstration purposes)

#owner
  #owner_from_list
    = f.association :owner, :collection => Person.all(:order => 'name'), :prompt => 'Choose an existing owner'
  = link_to_add_association 'add a new person as owner', f, :owner

This view part will either let you select an owner from the list of persons, or show the fields to add a new person as owner.

The callbacks can be added as follows:

$(document).ready(function() {
    $('#owner').bind('insertion-callback',
         function() {
           $("#owner_from_list").hide();
           $("#owner a.add_fields").hide();
         });
    $('#owner').bind("removal-callback",
         function() {
           $("#owner_from_list").show();
           $("#owner a.add_fields").show();
         });
});

Do note that for the callbacks to work there has to be a surrounding container (div), where you can bind the callbacks to.

Control the Insertion behaviour

The default insertion location is at the back of the current container. But we have added two data-attributes that are read to determine the insertion-node and -method.

For example:

$(document).ready(function() {
    $("#owner a.add_fields").
      data("association-insertion-method", 'before').
      data("association-insertion-node", 'this');
});

The association-insertion-node will determine where to add it. You can choose any selector here, or specify this (default it is the parent-container).

The association-insertion-method will determine where to add it in relation with the node. Any jQuery DOM Manipulation method can be set but we recommend sticking to any of the following: before, after, append, prepend. It is unknown at this time what others would do.

Partial

The partial should be named _<association-object_singular>_fields, and should start with a container (e.g. div) of class .nested-fields.

There is no limit to the amount of nesting, though.

Note on Patches/Pull Requests

Fork the project.
Make your feature addition or bug fix.
Add tests for it. This is important so I don't break it in a future version unintentionally.
Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
Send me a pull request. Bonus points for topic branches.

Todo

add more sample relations: has_many :through, belongs_to, ...
improve the tests (test the javascript too)(if anybody wants to lend a hand ...?)

eetteri/cocoon