awesome_nested_fields 0.0.3 → 0.1.0

data/.gitignore

@@ -1,3 +1,4 @@
 pkg/*
 *.gem
 .bundle
+demos/*/**

data/Gemfile.lock

@@ -0,0 +1,78 @@
+PATH
+  remote: .
+  specs:
+    awesome_nested_fields (0.0.3)
+      rails (>= 3.0.0)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    abstract (1.0.0)
+    actionmailer (3.0.4)
+      actionpack (= 3.0.4)
+      mail (~> 2.2.15)
+    actionpack (3.0.4)
+      activemodel (= 3.0.4)
+      activesupport (= 3.0.4)
+      builder (~> 2.1.2)
+      erubis (~> 2.6.6)
+      i18n (~> 0.4)
+      rack (~> 1.2.1)
+      rack-mount (~> 0.6.13)
+      rack-test (~> 0.5.7)
+      tzinfo (~> 0.3.23)
+    activemodel (3.0.4)
+      activesupport (= 3.0.4)
+      builder (~> 2.1.2)
+      i18n (~> 0.4)
+    activerecord (3.0.4)
+      activemodel (= 3.0.4)
+      activesupport (= 3.0.4)
+      arel (~> 2.0.2)
+      tzinfo (~> 0.3.23)
+    activeresource (3.0.4)
+      activemodel (= 3.0.4)
+      activesupport (= 3.0.4)
+    activesupport (3.0.4)
+    arel (2.0.8)
+    builder (2.1.2)
+    erubis (2.6.6)
+      abstract (>= 1.0.0)
+    i18n (0.5.0)
+    mail (2.2.15)
+      activesupport (>= 2.3.6)
+      i18n (>= 0.4.0)
+      mime-types (~> 1.16)
+      treetop (~> 1.4.8)
+    mime-types (1.16)
+    polyglot (0.3.1)
+    rack (1.2.1)
+    rack-mount (0.6.13)
+      rack (>= 1.0.0)
+    rack-test (0.5.7)
+      rack (>= 1.0)
+    rails (3.0.4)
+      actionmailer (= 3.0.4)
+      actionpack (= 3.0.4)
+      activerecord (= 3.0.4)
+      activeresource (= 3.0.4)
+      activesupport (= 3.0.4)
+      bundler (~> 1.0)
+      railties (= 3.0.4)
+    railties (3.0.4)
+      actionpack (= 3.0.4)
+      activesupport (= 3.0.4)
+      rake (>= 0.8.7)
+      thor (~> 0.14.4)
+    rake (0.8.7)
+    thor (0.14.6)
+    treetop (1.4.9)
+      polyglot (>= 0.3.1)
+    tzinfo (0.3.24)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  awesome_nested_fields!
+  bundler (>= 1.0.0)

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Lailson Bandeira
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,102 @@
+Awesome Nested Fields
+=====================
+
+In Rails, you can create forms that have fields from nested models. For example, if a person has many phone numbers, you can easily create a form that receives data from the person and from a fixed number of phones. However, when you want to allow the person to insert multiple, indefinite phones, you're in trouble: it's [much harder](http://railscasts.com/episodes/196-nested-model-form-part-1) [than it](http://railscasts.com/episodes/197-nested-model-form-part-2) [should be](http://stackoverflow.com/questions/1704142/unobtrusive-dynamic-form-fields-in-rails-with-jquery). Well, not anymore.
+
+
+Installation
+------------
+
+1. Add the gem to your Gemfile.
+
+        gem 'awesome_nested_fields'
+
+2. Run bundler to make sure the gem gets installed.
+
+        bundle install
+    
+3. Include the `jquery.nested-fields.js` file in your template (or in the pages that will use nested fields).
+    
+        <script src="/javascripts/jquery.nested-fields.js" type="text/javascript"></script>
+
+Now you're ready to rock with nested models. Don't forget to include the javascript file _after_ you've included jQuery. And don't worry because this file isn't on the public folder: it comes bundled into the gem.
+
+
+Basic Usage
+-----------
+
+### Model
+
+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
+
+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:
+
+        <%= form_for(@person) do |f| %>
+          <% # person fields... %>
+
+          <h2>Phones</h2>
+          <div class="container">
+            <%= nested_fields(f, :phones) %>
+          </div>
+          <a href="#" class="add">add phone</a>
+
+          <% # more person fields... %>
+        <% end %>
+
+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:
+
+        <fieldset class="item">
+          <%= f.label :where %>
+          <%= f.text_field :where %><br/>
+            
+          <%= f.label :number %>
+          <%= f.text_field :number %>
+
+          <a href="#" class="remove">remove</a>
+          
+          <%= f.hidden_field :id %>
+          <%= f.hidden_field :_destroy %>
+        </fieldset>
+
+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
+
+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):
+
+        $(document).ready(function(e) {
+          $('FORM').nestedFields();
+        });
+
+Now enjoy your new nested model form!
+
+
+Compatibility
+-------------
+
+awesome_nested_fields works only with Rails 3 and was tested with jQuery 1.5.0.
+
+
+TODO
+----
+
+* Write tests
+* Write awesome demos
+* Make sure it can degrade gracefully
+* Return and API object on JS to make interaction easier
+* Port JavaScript code to CoffeeScript
+
+
+Copyleft
+--------
+Copyleft (c) 2011 Lailson Bandeira (http://lailsonbandeira.com/). See LICENSE for details.

data/app/helpers/awesome_nested_fields_helper.rb

@@ -1,4 +1,10 @@
 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)
 
@@ -8,7 +14,7 @@ module AwesomeNestedFieldsHelper
     end
 
     if options[:none_partial] and builder.object.send(association).empty?
-      items << render(options[:none_partial], options[:builder_local] => f)
+      items << render(options[:none_partial])
     end
 
     items.html_safe
@@ -18,14 +24,14 @@ module AwesomeNestedFieldsHelper
     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: 'new_nested_item') do |f|
+      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: 'new_nested_item') do |f|
+        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
@@ -38,9 +44,10 @@ 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] ||= :builder
+    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

data/lib/awesome_nested_fields/version.rb

@@ -1,3 +1,3 @@
 module AwesomeNestedFields
-  VERSION = "0.0.3"
+  VERSION = "0.1.0"
 end

data/public/javascripts/jquery.nested-fields.js

@@ -10,8 +10,8 @@
     container: '.container',
     item: '.item',
     none: '.none',
-    addHandler: '.add',
-    removeHandler: '.remove',
+    add: '.add',
+    remove: '.remove',
     newItemIndex: 'new_nested_item'
   };
   
@@ -31,10 +31,10 @@
       options.itemTemplate = $(options.itemTemplate, $this);
       options.noneTemplate = $(options.noneTemplate, $this);
       options.container = $(options.container, $this);
-      options.addHandler = $(options.addHandler, $this);
+      options.add = $(options.add, $this);
       $this.data('nested-fields.options', options); 
       
-      options.addHandler.bind('click.nested-fields', function(e) {
+      options.add.bind('click.nested-fields', function(e) {
         e.preventDefault();
         var newItem = prepareTemplate(options);
         insertItemWithCallbacks(newItem, null, options);
@@ -165,17 +165,20 @@
   }
   
   function bindRemoveEvent(item, options) {
-    var removeHandler = $(item).find(options.removeHandler);
+    var removeHandler = $(item).find(options.remove);
     var needsConfirmation = removeHandler.attr('data-confirm');
     
-    var event = needsConfirmation ? 'confirmed' : 'click';
-    removeHandler.bind(event + '.nested-fields', function(e) {
-      removeItem(item, options);
+    var event = needsConfirmation ? 'confirm:complete' : 'click';
+    removeHandler.bind(event + '.nested-fields', function(e, confirmed) {
+      e.preventDefault();
+      if(confirmed === undefined || confirmed === true) {
+        removeItem(item, options);
+      }
     });
   }
   
   function insertNone(options) {
-    if(findItems(options).length == 0) {
+    if(findItems(options).length === 0) {
       options.container.append(options.noneTemplate.html());
     }
   }

metadata

@@ -1,13 +1,8 @@
 --- !ruby/object:Gem::Specification 
 name: awesome_nested_fields
 version: !ruby/object:Gem::Version 
-  hash: 25
-  prerelease: false
-  segments: 
-  - 0
-  - 0
-  - 3
-  version: 0.0.3
+  prerelease: 
+  version: 0.1.0
 platform: ruby
 authors: 
 - Lailson Bandeira
@@ -15,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-02-12 00:00:00 -03:00
+date: 2011-06-06 00:00:00 -03:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -26,11 +21,6 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 23
-        segments: 
-        - 1
-        - 0
-        - 0
         version: 1.0.0
   type: :development
   version_requirements: *id001
@@ -42,11 +32,6 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 7
-        segments: 
-        - 3
-        - 0
-        - 0
         version: 3.0.0
   type: :runtime
   version_requirements: *id002
@@ -61,6 +46,9 @@ extra_rdoc_files: []
 files: 
 - .gitignore
 - Gemfile
+- Gemfile.lock
+- LICENSE
+- README.md
 - Rakefile
 - app/helpers/awesome_nested_fields_helper.rb
 - awesome_nested_fields.gemspec
@@ -81,25 +69,17 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
       version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 23
-      segments: 
-      - 1
-      - 3
-      - 6
       version: 1.3.6
 requirements: []
 
 rubyforge_project: awesome_nested_fields
-rubygems_version: 1.3.7
+rubygems_version: 1.6.2
 signing_key: 
 specification_version: 3
 summary: Awesome nested fields for Rails