Note: this gem is deprecated. The gem has been renamed to cocoon, as it was not limited to formtastic alone.
Formtastic-cocoon is a Rails3 gem, extending formtastic, 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.
As this gem extends formtastic and uses jQuery, it is only useful to use this gem in a rails3 project where you are already using formtastic and jQuery.
I have a sample project where I demonstrate both.
Gemfile add the following:
Run the installation task:
rails g formtastic_cocoon:install
or using erb, you write
That is all you need to do to start using it!
Suppose you have a model
rails g scaffold Project name:string description:string
and a project has many
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 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
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.
How it works
I define two helper functions:
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
It takes three parameters:
- name: the text to show in the link
- f: referring to the containing formtastic form-object
- association: the name of the association (plural) of which a new instance needs to be added (symbol or string).
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
The partial should be named
_<association-object_singular>_fields, and should start with a div of class
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.
Copyright (c) 2010 nathanvda. See LICENSE for details.