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

Merge pull request #30 from silent-e/expand-insertion-methods

Browse Source 
Expand insertion methods and formatting tweaks
This commit is contained in:
Nathan Van der Auwera 2011-12-07 13:40:47 -08:00
commit bb97c88994
2 changed files with 117 additions and 87 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
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:
````ruby
gem "cocoon"
````
### Rails 3.1
Add the following to `application.js` so it compiles to the
asset_pipeline
`//= require cocoon`
````ruby
//= 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):
````ruby
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:
````haml
= javascript_include_tag :cocoon
````
or using erb, you write
````ruby
<%= javascript_include_tag :cocoon %>
````
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`:
````ruby
rails g scaffold Project name:string description:string
````
and a project has many `tasks`:
````ruby
rails g model Task description:string done:boolean project_id:integer
````
Edit the models to code the relation:
````ruby
class Project < ActiveRecord::Base
has_many :tasks
accepts_nested_attributes_for :tasks
@ -68,6 +83,7 @@ Edit the models to code the relation:
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
@ -79,6 +95,7 @@ We will show the sample usage with the different possible form-builders.
Inside our `projects/_form` partial we then write:
````haml
- f.inputs do
= f.input :name
= f.input :description
@ -90,14 +107,17 @@ Inside our `projects/_form` partial we then write:
= link_to_add_association 'add task', f, :tasks
-f.buttons do
= f.submit 'Save'
````
and inside the `_task_fields` partial we write:
````haml
.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!
@ -129,9 +149,11 @@ It takes four parameters:
- 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 two extra options that allow to conrol the placement of the new link-data:
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-position` : insert the new data `before` or `after` the given 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).
@ -153,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
be handed down as follows:
````haml
= 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 `onwer`
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)
````haml
#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:
````javascript
$(document).ready(function() {
$('#owner').bind('insertion-callback',
function() {
@ -183,25 +209,27 @@ The callbacks can be added as follows:
$("#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 -location.
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:
````javascript
$(document).ready(function() {
$("#owner a.add_fields").
data("association-insertion-position", 'before').
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-position` will determine where to add it in relation with the node. Only two options: `before` or `after`.
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
@ -224,7 +252,7 @@ There is no limit to the amount of nesting, though.
## Todo
* add more sample relations: has_many :through, belongs_to, ...
* add more sample relations: `has_many :through`, `belongs_to`, ...
* improve the tests (test the javascript too)(if anybody wants to lend a hand ...?)
## Copyright

42
app/assets/javascripts/cocoon.js
View File

@ -11,13 +11,14 @@
$('.add_fields').live('click', function(e) {
e.preventDefault();
var assoc = $(this).data('association'),
assocs = $(this).data('associations'),
content = $(this).data('template'),
insertionPosition = $(this).data('association-insertion-position'),
insertionNode = $(this).data('association-insertion-node'),
insertionCallback = $(this).data('insertion-callback'),
removalCallback = $(this).data('removal-callback'),
var $this = $(this),
assoc = $this.data('association'),
assocs = $this.data('associations'),
content = $this.data('template'),
insertionMethod = $this.data('association-insertion-method') || $this.data('association-insertion-position') || 'before';
insertionNode = $this.data('association-insertion-node'),
insertionCallback = $this.data('insertion-callback'),
removalCallback = $this.data('removal-callback'),
regexp_braced = new RegExp('\\[new_' + assoc + '\\]', 'g'),
regexp_underscord = new RegExp('_new_' + assoc + '_', 'g'),
new_id = new Date().getTime(),
@ -34,33 +35,34 @@
new_content = new_content.replace(regexp_underscord, newcontent_underscord);
if (insertionNode){
insertionNode = insertionNode == "this" ? $(this) : $(insertionNode);
insertionNode = insertionNode == "this" ? $this : $(insertionNode);
} else {
insertionNode = $(this).parent();
insertionNode = $this.parent();
}
var contentNode = $(new_content);
if (insertionPosition == 'after'){
insertionNode.after(contentNode);
} else {
insertionNode.before(contentNode);
}
// allow any of the jquery dom manipulation methods (after, before, append, prepend, etc)
// to be called on the node. allows the insertion node to be the parent of the inserted
// code and doesn't force it to be a sibling like after/before does. default: 'before'
insertionNode[insertionMethod](contentNode);
$(this).parent().trigger('insertion-callback');
$this.parent().trigger('insertion-callback');
});
$('.remove_fields.dynamic').live('click', function(e) {
trigger_removal_callback($(this));
var $this = $(this);
trigger_removal_callback($this);
e.preventDefault();
$(this).closest(".nested-fields").remove();
$this.closest(".nested-fields").remove();
});
$('.remove_fields.existing').live('click', function(e) {
trigger_removal_callback($(this));
var $this = $(this);
trigger_removal_callback($this);
e.preventDefault();
$(this).prev("input[type=hidden]").val("1");
$(this).closest(".nested-fields").hide();
$this.prev("input[type=hidden]").val("1");
$this.closest(".nested-fields").hide();
});
})(jQuery);