adapted readme

This commit is contained in:
nathanvda 2011-02-09 22:51:32 +01:00
parent dc09be5634
commit b1df25c4c3

View File

@ -1,35 +1,39 @@
# formtastic-cocoon # cocoon
Formtastic-cocoon is a Rails3 gem, extending formtastic, to allow easier handling of nested forms. 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. 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. 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 ## Prerequisites
As this gem extends formtastic and uses jQuery, it is only useful to use this gem in a rails3 This gem uses jQuery, it is most useful to use this gem in a rails3
project where you are already using formtastic and jQuery. project where you are already using jQuery.
I have a sample project where I demonstrate both. 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 ## Installation
Inside your `Gemfile` add the following: Inside your `Gemfile` add the following:
gem "formtastic_cocoon" gem "cocoon"
Run the installation task: Run the installation task:
rails g formtastic_cocoon:install rails g cocoon:install
This will install the needed javascript file. This will install the needed javascript file.
Inside your `application.html.haml` you will need to add below the default javascripts: Inside your `application.html.haml` you will need to add below the default javascripts:
= javascript_include_tag :formtastic_cocoon = javascript_include_tag :cocoon
or using erb, you write or using erb, you write
<%= javascript_include_tag :formtastic_cocoon %> <%= javascript_include_tag :cocoon %>
That is all you need to do to start using it! That is all you need to do to start using it!
@ -58,6 +62,10 @@ What we want to achieve is to get a form where we can add and remove the tasks d
What we need for this, is that the fields for a new/existing `task` are defined in a partial What we need for this, is that the fields for a new/existing `task` are defined in a partial
view called `_task_fields.html`. 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: Inside our `projects/_form` partial we then write:
- f.inputs do - f.inputs do
@ -84,6 +92,16 @@ That is all there is to it!
There is an example project on github implementing it called [formtastic-cocoon-demo](https://github.com/nathanvda/formtastic-cocoon-demo). There is an example project on github implementing it called [formtastic-cocoon-demo](https://github.com/nathanvda/formtastic-cocoon-demo).
### Using simple_form
There is only line that needs to change, instead of writing `semantic_fields_for` you write `simple_fields_for`.
I will provide a full example (and a sample project) later.
### Using standard rails forms
I provide a full example (and a sample project) later.
## How it works ## How it works
I define two helper functions: I define two helper functions:
@ -121,6 +139,12 @@ There is no limit to the amount of nesting, though.
(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) (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. * Send me a pull request. Bonus points for topic branches.
## Todo
* complete the sample projects for simple_form and normal rails forms
* complete the test-coverage
## Copyright ## Copyright
Copyright (c) 2010 nathanvda. See LICENSE for details. Copyright (c) 2010 Nathan Van der Auwera. See LICENSE for details.