awesome_nested_fields 0.2.0 → 0.3.1

data/README.md

@@ -26,7 +26,7 @@ Installation
 
         gem 'awesome_nested_fields'
 
-2. Copy the javascript dependency to `public\javascripts` by using the generator.
+2. Copy the javascript dependency to `public/javascripts` by using the generator.
 
         rails generate awesome_nested_fields:install
 
@@ -44,62 +44,144 @@ Basic Usage
 
 First, make sure the object that has the `has_many` or `has_and_belongs_to_many` relation accepts nested attributes for the collection you want. For example, if a person _has_many_ phones, we'll have a model like this:
 
-        class Person < ActiveRecord::Base
-          has_many :phones
-          accepts_nested_attributes_for :phones, allow_destroy: true
-        end
+    class Person < ActiveRecord::Base
+      has_many :phones
+      accepts_nested_attributes_for :phones, allow_destroy: true
+    end
 
 The `accepts_nested_attributes_for` is a method from Active Record that allows you to pass attributes of nested models directly to its parent, instead of instantiate each child object separately. In this case, `Person` gains a method called `phones_attributes=`, that accepts data for new and existing phones of a given person. The `allow_destroy` option enables us to also delete child objects. To know more about nested attributes, check out the [ActiveRecord::NestedAttribute](https://github.com/rails/rails/blob/master/activerecord/lib/active_record/nested_attributes.rb#L1) class.
 
 ### View
 
-The next step is set up the form view using the `nested_fields` helper method. It receives three parameters: the parent form builder, the association name and an optional hash of options (humm, a pun).
-Proceeding with the person/phones example, we can have a form like this:
+The next step is set up the form view with the `nested_fields_for` method. It receives the association/collection name, an optional hash of options (humm, a pun) and a block with the nested fields. Proceeding with the person/phones example, we can have a form like this:
+
+    <%= form_for(@person) do |f| %>
+      <% # person fields... %>
+      
+      <h2>Phones</h2>
+      <div class="container">
+        <%= f.nested_fields_for :phones do |f| %>
+          <fieldset class="item">
+            <%= f.label :number %>
+            <%= f.text_field :number %>
+            
+            <a href="#" class="remove">remove</a>
+            
+            <%= f.hidden_field :id %>
+            <%= f.hidden_field :_destroy %>
+          </fieldset>
+        <% end %>
+      </div>
+      <a href="#" class="add">add phone</a>
+      
+      <% # more person fields... %>
+    <% end %>
 
-        <%= form_for(@person) do |f| %>
-          <% # person fields... %>
+The `nested_fields_for` method lists the phones this person has and also adds an empty template to the page for creating new phones. (Actually, there is too much code inside the block. If you're not working with a simple example like this you better extract this code into a partial and call just `render :phones` inside the block. Good coding practices, you know.)
 
-          <h2>Phones</h2>
-          <div class="container">
-            <%= nested_fields(f, :phones) %>
-          </div>
-          <a href="#" class="add">add phone</a>
+If you're paying attention, you noticed the key elements are marked with special class names. We *need* this for the javascript code, so it knows what to do with each HTML element: the one that have the children must have the class `container`; each child must be marked with the class `item`; inside an item, the link for removal must have the class `remove`; and the link to add new items must have the class `add`. We can change the names later, but these are the default choices. Finally, don't forget to add the `id` field, as it is needed by AR to identify whether this is an existing or a new element, and the `_destroy` field  to activate deletion when the user clicks on the remove link.
 
-          <% # more person fields... %>
-        <% end %>
+### Javascript
 
-The `nested_fields` helper lists the phones this person has and also adds an empty template to the page for creating new phones. But where is the phone form? Well, awesome_nested_fields expects a partial with the association name in the singular (after all, the partial represents a single child object). In this case, it looks for the partial `phone` (we can change this name later). So, in the file `_phone.html.erb`, we can have:
+This is the easiest part: just activate the nested fields actions when the page loads. We can put this in the `application.js` file (or in any other place that gets executed in the page):
 
-        <fieldset class="item">
-          <%= f.label :where %>
-          <%= f.text_field :where %><br/>
-            
-          <%= f.label :number %>
-          <%= f.text_field :number %>
+    $(document).ready(function(e) {
+      $('FORM').nestedFields();
+    });
 
-          <a href="#" class="remove">remove</a>
-          
-          <%= f.hidden_field :id %>
-          <%= f.hidden_field :_destroy %>
-        </fieldset>
+Now enjoy your new nested model form!
 
-If you're paying attention, you noticed the key elements are marked with a special class name. We need this for the javascript code, so it knows what to do with each HTML element: the one that have the children must have the class `container`; each child must be marked with the class `item`; inside an item, the link for removal must have the class `remove`; and the link to add new items must have the class `add`. We can change the names later, but these are the default choices. Finally, don't forget to add the `id` field, as it is needed by AR to identify if this is an existing or a new element, and the `_destroy` field  to activate deletion when the user clicks on the remove link.
 
-### Javascript
+Reference
+---------
 
-This is the easiest part: just activate the nested fields actions when the page loads. We can put this in the `application.js` file (or in any other place that gets executed in the page):
+### View Options
+
+There are some view options, but most are internal. There is just one you really need to know about; for the others, go to the code.
+
+#### show_empty
+
+Sometimes you want to show something when the collection is empty. Just set `show_empty` to `true` and prepare the block to receive `nil` when the collection is empty. Awesome nested fields will take care to show the empty message when there are no elements and remove it when one is added.
+To implement this on the basic example, do something like:
+
+    <%= f.nested_fields_for :phones, show_empty: true do |f| %>
+      <% if f %>
+        <% fields code... %>
+      <% else %>
+        <p class="empty">There are no phones.</p>
+      <% end %>
+    <% end %>
+
+And yeah, you need to mark it with the class `empty` or any other selector configured via javascript.
 
-        $(document).ready(function(e) {
-          $('FORM').nestedFields();
+### Javascript Options
+
+#### Selectors
+
+To make nested fields work dynamically, the JS code needs to know what elements to use. By default, this is made by marking key elements with CSS classes, but you can use other selectors (any valid jQuery selector will do). The available options are shown below.
+
+* `itemSelector` marks each item from the collection (`.item` by default)
+* `containerSelector` marks the element that contains the items (`.container` by default)
+* `addSelector` marks the element that will add a new item to the container when clicked (`.add` by default)
+* `removeSelector` marks the element inside an item that will remove it when clicked (`.remove` by default)
+* `emptySelector` marks the element that is shown when there are no items; used in conjunction with `show_empty` option (`.empty` by default)
+
+For example, if you are using nested fields inside a table, you can do:
+
+    element.nestedFields({
+      containerSelector: 'tbody',
+      itemSelector: 'tr'
+    });
+    
+
+#### Callbacks
+
+Actions can be executed before or after items get inserted or removed. There are four callbacks available: `beforeInsert`, `afterInsert`, `beforeRemove` and `afterRemove`. All of them receive the item as the first parameter, so you can query or modify it before the operation.
+
+    element.nestedFields({
+      beforeInsert: function(item) {
+        item.css('color', 'red'); // Make some operation
+        console.log(item + ' will be inserted.')
+      },
+      afterRemove: function(item) {
+        console.log(item + ' was removed.');
+      }
+    });
+    
+The before callbacks also allow you to control when the element will be inserted or removed, so you can perform async operations (ajax, of course!) or choose to not insert or remove the element at all if some condition is not met. Just receive a second parameter as the handler function.
+    
+    element.nestedFields({
+      beforeInsert: function(item, insert) {
+        $.get('/ajax_function', function() {
+          insert();
         });
+      }
+    });
 
-Now enjoy your new nested model form!
+
+### Javascript API
+
+It is possible to control nested fields programmatically using a jQuery-style API.
+
+    element.nestedFields('insert', function(item) {
+      // Make some operation with item
+    }, {skipBefore: true});
+    
+The code above inserts a new item and does not execute the `beforeInsert` callback function. The complete list of available methods is shown below.
+
+* `insert(callback, options)` inserts a new item in the container. The `callback` function is executed just before the item is inserted. There are two available options: `skipBefore` and `skipAfter`. Both arguments are optional.
+* `remove(element, options)` removes `element` from the container. There are two available options: `skipBefore` and `skipAfter`. The last argument is optional.
+* `removeAll(options)` removes all elements from the container. There are two available options: `skipBefore` and `skipAfter`. The argument is optional.
+* `items()` returns a list of items on the container.
+* `destroy()` deactivates nested fields for the element.
+
+These methods can be called from the element where nested fields are applied (e.g. a form) or from any element inside it (e.g. an input or the container itself).
 
 
 Compatibility
 -------------
 
-awesome_nested_fields works only with Rails 3.0 and Rails 3.1. Sorry, Rails 2.x users.
+awesome_nested_fields works only with jQuery and Rails 3.x. Sorry, Rails 2.x users.
 
 
 TODO
@@ -108,8 +190,6 @@ TODO
 * Write tests
 * Write awesome demos
 * Make sure it can degrade gracefully
-* Return and API object on JS to make interaction easier
-* Make `nested_fields` call compatible with Rails `fields_for`
 
 
 Copyleft

data/lib/awesome_nested_fields.rb

@@ -7,3 +7,5 @@ module AwesomeNestedFields
   
   require 'awesome_nested_fields/version'
 end
+
+require 'rails/form_helper'

data/lib/awesome_nested_fields/version.rb

@@ -1,3 +1,3 @@
 module AwesomeNestedFields
-  VERSION = "0.2.0"
+  VERSION = "0.3.1"
 end

data/lib/rails/form_helper.rb

@@ -0,0 +1,34 @@
+ActionView::Helpers::FormBuilder.class_eval do
+  def nested_fields_for(association, options={}, &block)
+    raise ArgumentError, 'Missing block to nested_fields_for' unless block_given?
+    
+    options[:new_item_index] ||= 'new_nested_item'
+    options[:new_object] ||= self.object.class.reflect_on_association(association).klass.new
+    options[:item_template_class] ||= 'template item'
+    options[:empty_template_class] ||= 'template empty'
+    options[:show_empty] ||= false
+    
+    output = @template.capture { fields_for(association, &block) }
+    
+    if options[:show_empty] and self.object.send(association).empty?
+      output.safe_concat @template.capture { yield nil } 
+    end
+    
+    output.safe_concat nested_fields_templates(association, options, &block)
+    
+    output
+  end
+
+private
+  def nested_fields_templates(association, options, &block)
+    templates = @template.content_tag(:script, type: 'text/html', class: options[:item_template_class]) do
+      fields_for(association, options[:new_object], child_index: options[:new_item_index], &block)
+    end
+    
+    if options[:show_empty]
+      templates.safe_concat @template.content_tag(:script, type: 'text/html', class: options[:empty_template_class], &block)
+    end
+    
+    templates
+  end
+end

data/vendor/assets/javascripts/jquery.nested-fields.js

@@ -13,13 +13,13 @@
     afterInsert: function(item) {},
     beforeRemove: function(item, callback) { callback() },
     afterRemove: function(item) {},
-    itemTemplate: '.item.template',
-    noneTemplate: '.none.template',
-    container: '.container',
-    item: '.item',
-    none: '.none',
-    add: '.add',
-    remove: '.remove',
+    itemTemplateSelector: '.item.template',
+    emptyTemplateSelector: '.empty.template',
+    containerSelector: '.container',
+    itemSelector: '.item',
+    emptySelector: '.empty',
+    addSelector: '.add',
+    removeSelector: '.remove',
     newItemIndex: 'new_nested_item'
   };
   
@@ -36,35 +36,26 @@
       }
       
       options = $.extend({}, defaultSettings, options);
-      options.itemTemplate = $(options.itemTemplate, $this);
-      options.noneTemplate = $(options.noneTemplate, $this);
-      options.container = $(options.container, $this);
-      options.add = $(options.add, $this);
+      options.itemTemplate = $(options.itemTemplateSelector, $this);
+      options.emptyTemplate = $(options.emptyTemplateSelector, $this);
+      options.container = $(options.containerSelector, $this);
+      options.add = $(options.addSelector, $this);
       $this.data('nested-fields.options', options); 
       
-      options.add.bind('click.nested-fields', function(e) {
-        e.preventDefault();
-        var newItem = prepareTemplate(options);
-        insertItemWithCallbacks(newItem, null, options);
-      });
-      
-      $(options.item, options.container).each(function(i, item) {
-        bindRemoveEvent(item, options);
-      });
+      bindInsertToAdd(options);
+      bindRemoveToItems(options);
       
       return $this;
     },
     
     insert: function(callback, options) {
       options = $.extend({}, getOptions(this), options);
-      var newItem = prepareTemplate(options);
-      
-      insertItemWithCallbacks(newItem, callback, options);
+      return insertItemWithCallbacks(callback, options);
     },
     
     remove: function(element, options) {
       options = $.extend({}, getOptions(this), options);
-      return removeItem(element, options);
+      return removeItemWithCallbacks(element, options);
     },
     
     removeAll: function(options) {
@@ -94,6 +85,8 @@
     }
   };
   
+  // Initialization functions
+  
   function getOptions(element) {
     element = $(element);
     while(element.length > 0) {
@@ -107,6 +100,21 @@
     return null;
   }
   
+  function bindInsertToAdd(options) {
+    options.add.bind('click.nested-fields', function(e) {
+      e.preventDefault();
+      insertItemWithCallbacks(null, options);
+    });
+  }
+  
+  function bindRemoveToItems(options) {
+    $(options.itemSelector, options.containerSelector).each(function(i, item) {
+      bindRemoveToItem(item, options);
+    });
+  }
+  
+  // Insertion functions
+  
   function prepareTemplate(options) {
     var regexp = new RegExp(options.newItemIndex, 'g');
     var newId = new Date().getTime();
@@ -116,26 +124,27 @@
     newItem.attr('data-new-record', true);
     newItem.attr('data-record-id', newId);
     
-    bindRemoveEvent(newItem, options);
+    bindRemoveToItem(newItem, options);
     
     return newItem;
   }
   
-  function insertItem(newItem, options) {
-    removeNone(options);
-    options.container.append(newItem);
-  }
-  
-  function insertItemWithCallbacks(newItem, onInsertCallback, options) {  
+  function insertItemWithCallbacks(onInsertCallback, options) {  
+    var newItem = prepareTemplate(options);
+    
     function insert() {
       if(onInsertCallback) {
         onInsertCallback(newItem);
       }
-      insertItem(newItem, options);
+      removeEmpty(options);
+      options.container.append(newItem);
     }
     
-    if(!options.skipBefore) {
+    if(!options.skipBefore) {      
       options.beforeInsert(newItem, insert);
+      if(options.beforeInsert.length <= 1) {
+        insert();
+      }
     } else {
       insert();
     }
@@ -147,7 +156,13 @@
     return newItem;
   }
   
-  function removeItem(element, options) {
+  function removeEmpty(options) {
+    findEmpty(options).remove();
+  }
+  
+  // Removal functions
+  
+  function removeItemWithCallbacks(element, options) {
     function remove() {
       if($element.attr('data-new-record')) { // record is new
         $element.remove();
@@ -155,12 +170,15 @@
         $element.find("INPUT[name$='[_destroy]']").val('true');
         $element.hide();
       }
-      insertNone(options);
+      insertEmpty(options);
     }
     
     var $element = $(element);
     if(!options.skipBefore) {
       options.beforeRemove($element, remove);
+      if(options.beforeRemove.length <= 1) {
+        insert();
+      }
     } else {
       remove();
     }
@@ -172,35 +190,33 @@
     return $element;
   }
   
-  function bindRemoveEvent(item, options) {
-    var removeHandler = $(item).find(options.remove);
+  function insertEmpty(options) {
+    if(findItems(options).length === 0) {
+      options.container.append(options.emptyTemplate.html());
+    }
+  }
+  
+  function bindRemoveToItem(item, options) {
+    var removeHandler = $(item).find(options.removeSelector);
     var needsConfirmation = removeHandler.attr('data-confirm');
     
     var event = needsConfirmation ? 'confirm:complete' : 'click';
     removeHandler.bind(event + '.nested-fields', function(e, confirmed) {
       e.preventDefault();
       if(confirmed === undefined || confirmed === true) {
-        removeItem(item, options);
+        removeItemWithCallbacks(item, options);
       }
     });
   }
   
-  function insertNone(options) {
-    if(findItems(options).length === 0) {
-      options.container.append(options.noneTemplate.html());
-    }
-  }
-  
-  function removeNone(options) {
-    findNone(options).remove();
-  }
+  // Find functions
   
   function findItems(options) {
-    return options.container.find(options.item + ':visible');
+    return options.container.find(options.itemSelector + ':visible');
   }
   
-  function findNone(options) {
-    return options.container.find(options.none);
+  function findEmpty(options) {
+    return options.container.find(options.emptySelector);
   }
   
 })(jQuery);

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: awesome_nested_fields
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-07-03 00:00:00.000000000Z
+date: 2011-07-11 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &2156703520 !ruby/object:Gem::Requirement
+  requirement: &2155985320 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: 1.0.0
   type: :development
   prerelease: false
-  version_requirements: *2156703520
+  version_requirements: *2155985320
 - !ruby/object:Gem::Dependency
   name: rails
-  requirement: &2156703060 !ruby/object:Gem::Requirement
+  requirement: &2155984440 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,7 +32,7 @@ dependencies:
         version: 3.0.0
   type: :runtime
   prerelease: false
-  version_requirements: *2156703060
+  version_requirements: *2155984440
 description: Awesome dynamic nested fields for Rails and jQuery
 email: lailson@guava.com.br
 executables: []
@@ -45,13 +45,13 @@ files:
 - LICENSE
 - README.md
 - Rakefile
-- app/helpers/awesome_nested_fields_helper.rb
 - awesome_nested_fields.gemspec
 - lib/awesome_nested_fields.rb
 - lib/awesome_nested_fields/engine.rb
 - lib/awesome_nested_fields/railtie.rb
 - lib/awesome_nested_fields/version.rb
 - lib/generators/awesome_nested_fields/install/install_generator.rb
+- lib/rails/form_helper.rb
 - vendor/assets/javascripts/jquery.nested-fields.js
 homepage: http://rubygems.org/gems/awesome_nested_fields
 licenses: []

data/app/helpers/awesome_nested_fields_helper.rb

@@ -1,53 +0,0 @@
-module AwesomeNestedFieldsHelper
-  
-  def nested_fields(builder, association, options={})
-    nested_fields_items(builder, association, options) <<
-      nested_fields_template(builder, association, options)
-  end
-  
-  def nested_fields_items(builder, association, options={})
-    options = nested_fields_process_default_options(options, builder, association)
-
-    items = ''
-    builder.fields_for(association) do |f|
-      items << render(options[:partial], options[:builder_local] => f)
-    end
-
-    if options[:none_partial] and builder.object.send(association).empty?
-      items << render(options[:none_partial])
-    end
-
-    items.html_safe
-  end
-
-  def nested_fields_template(builder, association, options={})
-    options = nested_fields_process_default_options(options, builder, association)
-
-    templates = content_tag(:script, type: 'text/html', class: options[:item_template_class]) do
-      builder.fields_for(association, options[:new_object], child_index: options[:new_item_index]) do |f|
-        render(options[:partial], options[:builder_local] => f)
-      end
-    end
-
-    if options[:none_partial]
-      templates << content_tag(:script, type: 'text/html', class: options[:none_template_class]) do
-        builder.fields_for(association, options[:new_object], child_index: options[:new_item_index]) do |f|
-          render(options[:none_partial], options[:builder_local] => f)
-        end
-      end
-    end
-
-    templates.html_safe
-  end
-
-protected
-  def nested_fields_process_default_options(options, builder, association)
-    options[:new_object] ||= builder.object.class.reflect_on_association(association).klass.new
-    options[:partial] ||= association.to_s.singularize
-    options[:builder_local] ||= :f
-    options[:item_template_class] ||= 'template item'
-    options[:none_template_class] ||= 'template none'
-    options[:new_item_index] ||= 'new_nested_item'
-    options
-  end
-end