nested_form 0.2.2 → 0.2.3

data/CHANGELOG.rdoc

@@ -1,3 +1,15 @@
+0.2.3 (August 23, 2012)
+
+* Fix selector for deeply nested forms (thanks groe)
+
+* Fix association detection in #link_to remove (thanks nashbridges)
+
+* Add nested:fieldRemoved:type event (thanks nashbridges)
+
+* Add events for Prototype (thanks nashbridges)
+
+* Element.up() is the proper Prototype counter part to jQuery's closest() (thanks clemens)
+
 0.2.2 (July 9, 2012)
 
 * Make deeply-nested form working in jruby and rubinius

data/README.md

@@ -0,0 +1,165 @@
+# Nested Form
+
+[<img src="https://secure.travis-ci.org/ryanb/nested_form.png?branch=master" alt="Build Status" />](http://travis-ci.org/ryanb/nested_form)
+
+This is a Rails gem for conveniently manage multiple nested models in a single form. It does so in an unobtrusive way through jQuery or Prototype.
+
+This gem only works with Rails 3. See the [rails2 branch](https://github.com/ryanb/nested_form/tree/rails2) for a plugin to work in Rails 2.
+
+An example project showing how this works is available in the [complex-nested-forms/nested_form branch](https://github.com/ryanb/complex-form-examples/tree/nested_form).
+
+
+## Setup
+
+Add it to your Gemfile then run `bundle` to install it.
+
+```ruby
+gem "nested_form"
+```
+
+And then add it to the Asset Pipeline in the application.js file:
+
+```
+//= require jquery_nested_form
+```
+
+### Non Asset Pipeline Setup
+
+If you do not use the asset pipeline, run this generator to create the JavaScript file.
+
+```
+rails g nested_form:install
+```
+
+You can then include the generated JavaScript in your layout.
+
+```erb
+<%= javascript_include_tag :defaults, "nested_form" %>
+```
+
+## Usage
+
+Imagine you have a `Project` model that `has_many :tasks`. To be able to use this gem, you'll need to add `accepts_nested_attributes_for :tasks` to your Project model. If you wish to allow the nested objects to be destroyed, then add the `:allow_destroy => true` option to that declaration. If you don't have the `accepts_nested_attributes_for :tasks` you'll get a Missing Block Error. See the [accepts_nested_attributes_for documentation](http://api.rubyonrails.org/classes/ActiveRecord/NestedAttributes/ClassMethods.html#method-i-accepts_nested_attributes_for) for details on all available options.
+
+This will create a `tasks_attributes=` method, so you may need to add it to the `attr_accessible` array (`attr_accessible :tasks_attributes`).
+
+Then use the `nested_form_for` helper method to enable the nesting.
+
+```erb
+<%= nested_form_for @project do |f| %>
+```
+
+You will then be able to use `link_to_add` and `link_to_remove` helper methods on the form builder in combination with fields_for to dynamically add/remove nested records.
+
+```erb
+<%= f.fields_for :tasks do |task_form| %>
+  <%= task_form.text_field :name %>
+  <%= task_form.link_to_remove "Remove this task" %>
+<% end %>
+<p><%= f.link_to_add "Add a task", :tasks %></p>
+```
+
+
+## SimpleForm and Formtastic Support
+
+Use `simple_nested_form_for` or `semantic_nested_form_for` for SimpleForm and Formtastic support respectively.
+
+
+## Partials
+
+It is often desirable to move the nested fields into a partial to keep things organized. If you don't supply a block to fields_for it will look for a partial and use that.
+
+```erb
+<%= f.fields_for :tasks %>
+```
+
+In this case it will look for a partial called "task_fields" and pass the form builder as an `f` variable to it.
+
+
+## JavaScript events
+
+Sometimes you want to do some additional work after element was added or removed, but only
+after DOM was _really_ modified. In this case simply listening for click events on
+'Add new'/'Remove' link won't reliably work, because your code and code that inserts/removes
+nested field will run concurrently.
+
+This problem can be solved, because after adding or removing the field a set of custom events
+is triggered on this field. Using form example from above, if you click on the "Add a task" link,
+`nested:fieldAdded` and `nested:fieldAdded:tasks` will be triggered, while
+`nested:fieldRemoved` and `nested:fieldRemoved:tasks` will be triggered if you click
+"Remove this task" then.
+
+These events bubble up the DOM tree, going through `form` element, until they reach the `document`.
+This allows you to listen for the event and trigger some action accordingly. Field element, upon
+which action was made, is passed along with the `event` object. In jQuery you can access it
+via `event.field`, in Prototype the same field will be in `event.memo.field`.
+
+For example, you have a date input in a nested field and you want to use jQuery datepicker
+for it. This is a bit tricky, because you have to activate datepicker after field was inserted.
+
+### jQuery
+
+```javascript
+$(document).on('nested:fieldAdded', function(event){
+  // this field was just inserted into your form
+  var field = event.field; 
+  // it's a jQuery object already! Now you can find date input
+  var dateField = field.find('.date');
+  // and activate datepicker on it
+  dateField.datepicker();
+})
+```
+
+### Prototype
+
+```javascript
+document.observe('nested:fieldAdded', function(event){
+  var field = event.memo.field;
+  // it's already extended by Prototype
+  var dateField = field.down('.date');
+  dateField.datepicker();
+})  
+```
+
+Second type of event (i.e. `nested:fieldAdded:tasks`) is useful then you have more than one type
+of nested fields on a form (i.e. tasks and milestones) and want to distinguish, which exactly
+was added/deleted.
+
+See also [how to limit max count of nested fields](https://github.com/ryanb/nested_form/wiki/How-to:-limit-max-count-of-nested-fields)
+
+## Enhanced jQuery JavaScript template
+
+You can override default behavior of inserting new subforms into your form. For example:
+
+```javascript
+window.nestedFormEvents.insertFields = function(content, assoc, link) {
+  return $(link).closest('form').find(assoc + '_fields').append($(content));
+}
+```
+
+## Project Status
+
+Unfortunately I have not had time to actively work on this project recently. If you find a critical issue where it does not work as documented please [ping me on Twitter](http://twitter.com/rbates) and I'll take a look.
+
+## Contributing
+
+If you have any issues with Nested Form not addressed above or in the [example project](http://github.com/ryanb/complex-form-examples/tree/nested_form), please add an [issue on GitHub](http://github.com/ryanb/nested_form/issues) or [fork the project](http://help.github.com/fork-a-repo) and send a [pull request](http://help.github.com/send-pull-requests). To run the specs:
+
+```
+bundle install
+bundle exec rake spec:install
+bundle exec rake db:migrate
+bundle exec rake spec:all
+```
+
+See available rake tasks using `bundle exec rake -T`.
+
+## Special Thanks
+
+This gem was originally based on the solution by Tim Riley in his [complex-form-examples fork](https://github.com/timriley/complex-form-examples/tree/unobtrusive-jquery-deep-fix2).
+
+Thank you Andrew Manshin for the Rails 3 transition, [Andrea Singh](https://github.com/madebydna) for converting to a gem and [Peter Giacomo Lombardo](https://github.com/pglombardo) for Prototype support.
+
+Andrea also wrote a great [blog post](http://blog.madebydna.com/all/code/2010/10/07/dynamic-nested-froms-with-the-nested-form-gem.html) on the internal workings of this gem.
+
+Thanks [Pavel Forkert](https://github.com/fxposter) for the SimpleForm and Formtastic support.

data/Rakefile

@@ -14,26 +14,33 @@ end
 task :default => :spec
 
 namespace :db do
+  desc 'Prepare sqlite database'
   task :migrate do
     system 'cd spec/dummy && rake db:migrate RAILS_ENV=test && rake db:migrate RAILS_ENV=development'
   end
 end
 
 namespace :spec do
+  desc 'Install gems from additional gemfiles'
   task :install do
     system 'bundle install'
+    ENV.delete('GEM_HOME')
     ENV['BUNDLE_GEMFILE'] = File.expand_path('../gemfiles/Gemfile.rails3_1', __FILE__)
     system 'bundle install'
     ENV['BUNDLE_GEMFILE'] = File.expand_path('../gemfiles/Gemfile.rails3_0', __FILE__)
     system 'bundle install'
   end
 
+  desc 'Run tests with Rails 3.1.x'
   task :rails3_1 do
+    ENV.delete('GEM_HOME')
     ENV['BUNDLE_GEMFILE'] = File.expand_path('../gemfiles/Gemfile.rails3_1', __FILE__)
     Rake::Task["spec"].execute
   end
 
+  desc 'Run tests with Rails 3.0.x'
   task :rails3_0 do
+    ENV.delete('GEM_HOME')
     ENV['BUNDLE_GEMFILE'] = File.expand_path('../gemfiles/Gemfile.rails3_0', __FILE__)
     Rake::Task["spec"].execute
   end

data/lib/nested_form/builder_mixin.rb

@@ -14,13 +14,19 @@ module NestedForm
     def link_to_add(*args, &block)
       options = args.extract_options!.symbolize_keys
       association = args.pop
+
+      unless (reflection = object.class.reflect_on_association(association))
+        raise ArgumentError, "Failed to find #{object.class.name} association by name \"#{association}\""
+      end
+      model_object = reflection.klass.new
+
       options[:class] = [options[:class], "add_nested_fields"].compact.join(" ")
       options["data-association"] = association
       args << (options.delete(:href) || "javascript:void(0)")
       args << options
+      
       @fields ||= {}
       @template.after_nested_form(association) do
-        model_object = object.class.reflect_on_association(association).klass.new
         blueprint = fields_for(association, model_object, :child_index => "new_#{association}", &@fields[association])
         blueprint_options = {:id => "#{association}_fields_blueprint", :style => 'display: none'}
         @template.content_tag(:div, blueprint, blueprint_options)
@@ -42,6 +48,12 @@ module NestedForm
     def link_to_remove(*args, &block)
       options = args.extract_options!.symbolize_keys
       options[:class] = [options[:class], "remove_nested_fields"].compact.join(" ")
+      
+      # Extracting "milestones" from "...[milestones_attributes][...]"
+      md = object_name.to_s.match /(\w+)_attributes\]\[[\w\d]+\]$/
+      association = md && md[1]
+      options["data-association"] = association
+      
       args << (options.delete(:href) || "javascript:void(0)")
       args << options
       (hidden_field(:_destroy) << @template.link_to(*args, &block)).html_safe

data/spec/dummy/app/assets/javascripts/jquery_events_test.js

@@ -0,0 +1,19 @@
+$(function() {
+  var log = function(text) {
+    $('<p/>', {text: text}).appendTo('#console');
+  };
+
+  ['Added', 'Removed'].forEach(function(action) {
+    $(document).on('nested:field' + action, function(e) {
+      log(action + ' some field')
+    });
+
+    $(document).on('nested:field' + action + ':tasks', function(e) {
+      log(action + ' task field')
+    });
+
+    $(document).on('nested:field' + action + ':milestones', function(e) {
+      log(action + ' milestone field')
+    });
+  });
+});

data/spec/dummy/app/assets/javascripts/jquery_nested_form.js

@@ -13,7 +13,7 @@ jQuery(function($) {
 
       // Make the context correct by replacing new_<parents> with the generated ID
       // of each of the parent objects
-      var context = ($(link).closest('.fields').find('input:first').attr('name') || '').replace(new RegExp('\[[a-z]+\]$'), '');
+      var context = ($(link).closest('.fields').closestChild('input, textarea').eq(0).attr('name') || '').replace(new RegExp('\[[a-z]+\]$'), '');
 
       // context will be something like this for a brand new form:
       // project[tasks_attributes][new_1255929127459][assignments_attributes][new_1255929128105]
@@ -42,7 +42,8 @@ jQuery(function($) {
       content     = content.replace(regexp, "new_" + new_id);
 
       var field = this.insertFields(content, assoc, link);
-      $(link).closest("form")
+      // bubble up event upto document (through form)
+      field
         .trigger({ type: 'nested:fieldAdded', field: field })
         .trigger({ type: 'nested:fieldAdded:' + assoc, field: field });
       return false;
@@ -51,16 +52,18 @@ jQuery(function($) {
       return $(content).insertBefore(link);
     },
     removeFields: function(e) {
-      var link = e.currentTarget;
-      var hiddenField = $(link).prev('input[type=hidden]');
+      var $link = $(e.currentTarget),
+          assoc = $link.data('association'); // Name of child to be removed
+      
+      var hiddenField = $link.prev('input[type=hidden]');
       hiddenField.val('1');
-      // if (hiddenField) {
-      //   $(link).v
-      //   hiddenField.value = '1';
-      // }
-      var field = $(link).closest('.fields');
+      
+      var field = $link.closest('.fields');
       field.hide();
-      $(link).closest("form").trigger({ type: 'nested:fieldRemoved', field: field });
+      
+      field
+        .trigger({ type: 'nested:fieldRemoved', field: field })
+        .trigger({ type: 'nested:fieldRemoved:' + assoc, field: field });
       return false;
     }
   };
@@ -69,3 +72,32 @@ jQuery(function($) {
   $('form a.add_nested_fields').live('click', nestedFormEvents.addFields);
   $('form a.remove_nested_fields').live('click', nestedFormEvents.removeFields);
 });
+// http://plugins.jquery.com/project/closestChild
+/*
+ * Copyright 2011, Tobias Lindig
+ *
+ * Dual licensed under the MIT (http://www.opensource.org/licenses/mit-license.php)
+ * and GPL (http://www.opensource.org/licenses/gpl-license.php) licenses.
+ *
+ */
+(function($) {
+        $.fn.closestChild = function(selector) {
+                // breadth first search for the first matched node
+                if (selector && selector != '') {
+                        var queue = [];
+                        queue.push(this);
+                        while(queue.length > 0) {
+                                var node = queue.shift();
+                                var children = node.children();
+                                for(var i = 0; i < children.length; ++i) {
+                                        var child = $(children[i]);
+                                        if (child.is(selector)) {
+                                                return child; //well, we found one
+                                        }
+                                        queue.push(child);
+                                }
+                        }
+                }
+                return $();//nothing found
+        };
+})(jQuery);

data/spec/dummy/app/assets/javascripts/prototype_events_test.js

@@ -0,0 +1,20 @@
+document.observe('dom:loaded', function() {
+  var log = function(text) {
+    var p = new Element('p').update(text);
+    $('console').insert(p);
+  };
+
+  ['Added', 'Removed'].forEach(function(action) {
+    document.observe('nested:field' + action, function(e) {
+      log(action + ' some field')
+    });
+
+    document.observe('nested:field' + action + ':tasks', function(e) {
+      log(action + ' task field')
+    });
+
+    document.observe('nested:field' + action + ':milestones', function(e) {
+      log(action + ' milestone field')
+    });
+  });
+});

data/spec/dummy/app/assets/javascripts/prototype_nested_form.js

@@ -1,22 +1,22 @@
 document.observe('click', function(e, el) {
-	if (el = e.findElement('form a.add_nested_fields')) {
-	  // Setup
-	  var assoc   = el.readAttribute('data-association');           // Name of child
-	  var content = $(assoc + '_fields_blueprint').innerHTML; // Fields template
+  if (el = e.findElement('form a.add_nested_fields')) {
+    // Setup
+    var assoc   = el.readAttribute('data-association');           // Name of child
+    var content = $(assoc + '_fields_blueprint').innerHTML; // Fields template
 
-	  // Make the context correct by replacing new_<parents> with the generated ID
-	  // of each of the parent objects
-	  var context = (el.getOffsetParent('.fields').firstDescendant().readAttribute('name') || '').replace(new RegExp('\[[a-z]+\]$'), '');
+    // Make the context correct by replacing new_<parents> with the generated ID
+    // of each of the parent objects
+    var context = (el.getOffsetParent('.fields').firstDescendant().readAttribute('name') || '').replace(new RegExp('\[[a-z]+\]$'), '');
 
-	  // context will be something like this for a brand new form:
-	  // project[tasks_attributes][new_1255929127459][assignments_attributes][new_1255929128105]
-	  // or for an edit form:
-	  // project[tasks_attributes][0][assignments_attributes][1]
-	  if(context) {
-	    var parent_names = context.match(/[a-z_]+_attributes/g) || [];
-	    var parent_ids   = context.match(/(new_)?[0-9]+/g) || [];
+    // context will be something like this for a brand new form:
+    // project[tasks_attributes][new_1255929127459][assignments_attributes][new_1255929128105]
+    // or for an edit form:
+    // project[tasks_attributes][0][assignments_attributes][1]
+    if(context) {
+      var parent_names = context.match(/[a-z_]+_attributes/g) || [];
+      var parent_ids   = context.match(/(new_)?[0-9]+/g) || [];
 
-	    for(i = 0; i < parent_names.length; i++) {
+      for(i = 0; i < parent_names.length; i++) {
         if(parent_ids[i]) {
           content = content.replace(
             new RegExp('(_' + parent_names[i] + ')_.+?_', 'g'),
@@ -26,26 +26,31 @@ document.observe('click', function(e, el) {
             new RegExp('(\\[' + parent_names[i] + '\\])\\[.+?\\]', 'g'),
             '$1[' + parent_ids[i] + ']');
         }
-	    }
-	  }
+      }
+    }
 
-	  // Make a unique ID for the new child
-	  var regexp  = new RegExp('new_' + assoc, 'g');
-	  var new_id  = new Date().getTime();
-	  content     = content.replace(regexp, "new_" + new_id);
+    // Make a unique ID for the new child
+    var regexp  = new RegExp('new_' + assoc, 'g');
+    var new_id  = new Date().getTime();
+    content     = content.replace(regexp, "new_" + new_id);
 
-	  el.insert({ before: content });
-	  return false;
-	}
+    var field = el.insert({ before: content });
+    field.fire('nested:fieldAdded', {field: field});
+    field.fire('nested:fieldAdded:' + assoc, {field: field});
+    return false;
+  }
 });
 
 document.observe('click', function(e, el) {
-  	if (el = e.findElement('form a.remove_nested_fields')) {
-		var hidden_field = el.previous(0);
-		if(hidden_field) {
-		  hidden_field.value = '1';
-		}
-		el.ancestors()[0].hide();
-		return false;
-	}
+  if (el = e.findElement('form a.remove_nested_fields')) {
+    var hidden_field = el.previous(0),
+        assoc = el.readAttribute('data-association'); // Name of child to be removed
+    if(hidden_field) {
+      hidden_field.value = '1';
+    }
+    var field = el.up('.fields').hide();
+    field.fire('nested:fieldRemoved', {field: field});
+    field.fire('nested:fieldRemoved:' + assoc, {field: field});
+    return false;
+  }
 });