github-migration/cocoon
1
0
Fork 0
Code Issues Pull Requests 1 Packages Projects Releases Wiki Activity

update README with github flavored syntax highlighting

Browse Source
This commit is contained in:
silent-e 2011-12-06 12:15:58 -08:00
parent 4563b685be
commit 3ac8b8901d
1 changed files with 82 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
README.markdown
View File

@ -22,29 +22,39 @@ I have a sample project where I demonstrate the use of cocoon with formtastic.
Inside your `Gemfile` add the following: Inside your `Gemfile` add the following:
````ruby
gem "cocoon" gem "cocoon"
````
### Rails 3.1 ### Rails 3.1
Add the following to `application.js` so it compiles to the Add the following to `application.js` so it compiles to the
asset_pipeline asset_pipeline
`//= require cocoon` ````ruby
//= require cocoon
````
### Rails 3.x ### 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): If you are using Rails 3.0.x, you need to run the installation task (since rails 3.1 this is no longer needed):
````ruby
rails g 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:
````haml
= javascript_include_tag :cocoon = javascript_include_tag :cocoon
````
or using erb, you write or using erb, you write
````ruby
<%= javascript_include_tag :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!
@ -52,14 +62,19 @@ That is all you need to do to start using it!
Suppose you have a model `Project`: Suppose you have a model `Project`:
````ruby
rails g scaffold Project name:string description:string rails g scaffold Project name:string description:string
````
and a project has many `tasks`: and a project has many `tasks`:
````ruby
rails g model Task description:string done:boolean project_id:integer rails g model Task description:string done:boolean project_id:integer
````
Edit the models to code the relation: Edit the models to code the relation:
````ruby
class Project < ActiveRecord::Base class Project < ActiveRecord::Base
has_many :tasks has_many :tasks
accepts_nested_attributes_for :tasks accepts_nested_attributes_for :tasks
@ -68,6 +83,7 @@ Edit the models to code the relation:
class Task < ActiveRecord::Base class Task < ActiveRecord::Base
belongs_to :project belongs_to :project
end end
````
What we want to achieve is to get a form where we can add and remove the tasks dynamically. 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 What we need for this, is that the fields for a new/existing `task` are defined in a partial
@ -79,6 +95,7 @@ We will show the sample usage with the different possible form-builders.
Inside our `projects/_form` partial we then write: Inside our `projects/_form` partial we then write:
````haml
- f.inputs do - f.inputs do
= f.input :name = f.input :name
= f.input :description = f.input :description
@ -90,14 +107,17 @@ Inside our `projects/_form` partial we then write:
= link_to_add_association 'add task', f, :tasks = link_to_add_association 'add task', f, :tasks
-f.buttons do -f.buttons do
= f.submit 'Save' = f.submit 'Save'
````
and inside the `_task_fields` partial we write: and inside the `_task_fields` partial we write:
````haml
.nested-fields .nested-fields
= f.inputs do = f.inputs do
= f.input :description = f.input :description
= f.input :done, :as => :boolean = f.input :done, :as => :boolean
= link_to_remove_association "remove task", f = link_to_remove_association "remove task", f
````
That is all there is to it! That is all there is to it!
@ -118,7 +138,7 @@ I will provide a full example (and a sample project) later.
I define two helper functions: I define two helper functions:
### `link_to_add_association` ### 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 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`. This should be placed below the `semantic_fields_for`.
@ -138,7 +158,7 @@ It takes four parameters:
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). 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` ### link_to_remove_association
This function will add a link to your markup that will, when clicked, dynamically remove the surrounding partial form. 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`. This should be placed inside the partial `_<association-object-singular>_fields`.
@ -155,24 +175,28 @@ Inside the `html_options` you can add an option `:render_options`, and the conta
form. E.g. especially when using `twitter-bootstrap` and `simple_form` together, the `simple_fields_for` needs the option `:wrapper => 'inline'` which can 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: be handed down as follows:
````haml
= link_to_add_association 'add something', f, :something, :render_options => {:wrapper => 'inline' } = link_to_add_association 'add something', f, :something, :render_options => {:wrapper => 'inline' }
````
### Callbacks (upon insert and remove of items) ### 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` 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) (we use slim for demonstration purposes)
````haml
#owner #owner
#owner_from_list #owner_from_list
= f.association :owner, :collection => Person.all(:order => 'name'), :prompt => 'Choose an existing owner' = 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 = 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. 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: The callbacks can be added as follows:
````javascript
$(document).ready(function() { $(document).ready(function() {
$('#owner').bind('insertion-callback', $('#owner').bind('insertion-callback',
function() { function() {
@ -185,6 +209,7 @@ The callbacks can be added as follows:
$("#owner a.add_fields").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. Do note that for the callbacks to work there has to be a surrounding container (div), where you can bind the callbacks to.
@ -194,12 +219,13 @@ The default insertion location is at the back of the current container. But we h
For example: For example:
````javascript
$(document).ready(function() { $(document).ready(function() {
$("#owner a.add_fields"). $("#owner a.add_fields").
data("association-insertion-method", 'before'). data("association-insertion-method", 'before').
data("association-insertion-node", 'this'); 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-node` will determine where to add it. You can choose any selector here, or specify this (default it is the parent-container).