<commit_before># cocoon

[![Build Status](https://travis-ci.org/nathanvda/cocoon.png?branch=master)](https://travis-ci.org/nathanvda/cocoon)

Cocoon makes it easier to handle nested forms.

Nested forms are forms that handle nested models and attributes in one form;
e.g. a project with its tasks or an invoice with its line items.

Cocoon is form builder-agnostic, so it works with standard Rails, [Formtastic](https://github.com/justinfrench/formtastic), or [SimpleForm](https://github.com/plataformatec/simple_form).
It is compatible with rails 3 and rails 4.

This project is not related to [Apache Cocoon](http://cocoon.apache.org/).

## Prerequisites

This gem depends on jQuery, so it's most useful in a Rails 3 project where you are already using jQuery.
Furthermore, I would advise you to use either [Formtastic](https://github.com/justinfrench/formtastic) or [SimpleForm](https://github.com/plataformatec/simple_form).

## Installation

Inside your `Gemfile` add the following:

```ruby
gem "cocoon"
```

> Please note that for rails 4 you will need at least v1.2.0 or later.

### Rails 3.1+/Rails 4

Add the following to `application.js` so it compiles to the asset pipeline:

```ruby
//= require cocoon
```

### Rails 3.0.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):

```bash
rails g cocoon:install
```

This will install the Cocoon JavaScript file. In your application layout, add the following below the default javascripts:

```haml
= javascript_include_tag :cocoon
```

## Basic Usage

Suppose you have a `Project` model:

```bash
rails g scaffold Project name:string description:string
```

And a project has many `tasks`:

```bash
rails g model Task description:string done:boolean project:belongs_to
```

Your models are associated like this:

```ruby
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
```

Now we want a project form where we can add and remove tasks dynamically.
To do this, we need the fields for a new or existing `task` to be defined in a partial
named `_task_fields.html`.

### Rails 4/Strong Parameters Gotcha

Cocoon uses an additional parameter `_destroy` when rendering multiple instances of the partial form. When a user clicks the link `link_to_remove_association` generates, the partial is hidden with the parameter `_destroy` set to `1`.

In order for an association to be deleted on an update, you must explicitly to add `:_destroy` to the list of permitted parameters like so:

```ruby
  def project_params
    params.require(:project).permit(:name, :description, tasks_attributes: [:id, :description, :done, :_destroy])
  end
```

## Examples

### Formtastic

In our `projects/_form` partial we'd write:

```haml
= 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.actions do
    = f.action :submit
```

And in our `_task_fields` partial we'd write:<commit_msg>Small changes to the wording of strong parameters gotcha.<commit_after># cocoon

[![Build Status](https://travis-ci.org/nathanvda/cocoon.png?branch=master)](https://travis-ci.org/nathanvda/cocoon)

Cocoon makes it easier to handle nested forms.

Nested forms are forms that handle nested models and attributes in one form;
e.g. a project with its tasks or an invoice with its line items.

Cocoon is form builder-agnostic, so it works with standard Rails, [Formtastic](https://github.com/justinfrench/formtastic), or [SimpleForm](https://github.com/plataformatec/simple_form).
It is compatible with rails 3 and rails 4.

This project is not related to [Apache Cocoon](http://cocoon.apache.org/).

## Prerequisites

This gem depends on jQuery, so it's most useful in a Rails 3 project where you are already using jQuery.
Furthermore, I would advise you to use either [Formtastic](https://github.com/justinfrench/formtastic) or [SimpleForm](https://github.com/plataformatec/simple_form).

## Installation

Inside your `Gemfile` add the following:

```ruby
gem "cocoon"
```

> Please note that for rails 4 you will need at least v1.2.0 or later.

### Rails 3.1+/Rails 4

Add the following to `application.js` so it compiles to the asset pipeline:

```ruby
//= require cocoon
```

### Rails 3.0.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):

```bash
rails g cocoon:install
```

This will install the Cocoon JavaScript file. In your application layout, add the following below the default javascripts:

```haml
= javascript_include_tag :cocoon
```

## Basic Usage

Suppose you have a `Project` model:

```bash
rails g scaffold Project name:string description:string
```

And a project has many `tasks`:

```bash
rails g model Task description:string done:boolean project:belongs_to
```

Your models are associated like this:

```ruby
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
```

Now we want a project form where we can add and remove tasks dynamically.
To do this, we need the fields for a new or existing `task` to be defined in a partial
named `_task_fields.html`.

### Strong Parameters Gotcha

To destroy nested models, rails uses a virtual attribute called `_destroy`.
When `_destroy` is set, the nested model will be deleted.

When using strong parameters (default in rails 4), you need to explicitly
add `:_destroy` to the list of permitted parameters.

E.g. in your `ProjectsController`:

```ruby
  def project_params
    params.require(:project).permit(:name, :description, tasks_attributes: [:id, :description, :done, :_destroy])
  end
```



## Examples

### Formtastic

In our `projects/_form` partial we'd write:

```haml
= 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.actions do
    = f.action :submit
```

And in our `_task_fields` partial we'd write:
{'fraction_non_alphanumeric': 0.10182726846790567, 'fraction_numerical': 0.005778541308761518, 'mean_word_length': 4.422523285351397, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 11, 'https://': 12, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '296427', 'n_tokens_mistral': 2075, 'n_tokens_neox': 1925, 'n_words': 783}