nested_fields 0.3.0 → 0.4.0

data/README.rdoc

@@ -1,31 +1,81 @@
 = Nested Fields
 
-nested_fields is an Engine designed for generic, dynamic nested forms which may be N>=1 levels deep.
+An engine designed for generic, dynamic nested forms which may be N>=1 levels deep.
 
-Of what I could find, the existing solutions for dynamic nested forms in Rails are implemented with javascript rather through Controllers. It is my understanding that this is because FormBuilders cannot be passed as params to Controllers.
+Popular existing solutions for dynamic nested forms in Rails are implemented with javascript rather through controllers, probably because FormBuilders cannot be passed as params.
 
-It does rely on some {parsing behavior}[http://guides.rubyonrails.org/form_helpers.html] within Rails which may or may not be intended for use in this manner.
+It relies on some {parsing behavior}[http://guides.rubyonrails.org/form_helpers.html] within Rails which may be subject to change.
+
+It handles both +has_many+ and +has_one+ relationships. For +has_one+, it will allow 0..1 nested associates.
 
 == Requirements
 
-Designed for Rails 3 applications.
+Rails 3, jQuery
+
+== Styling
 
-jQuery is required. In the future, this requirement could be removed without much difficulty.
++nested_fields+ is not opinionated with regard to markup. Users are encouraged to provide their own styles.
 
 == Install
 
-Add nested_fields to the Gemfile and bundle install.
+Add +nested_fields+ to the Gemfile and bundle install. The engine's path provides the necessary javascript.
+
+== Associations
+
+=== +has_many+
+
+Each nested +has_many+ association will be bounded by a +fieldset+ with a link to add. Each of its associates will have a link to remove.
+
+=== +has_one+
+
+Each nested +has_one+ association will be bounded by a +fieldset+ with a checkbox for toggling the presence of an associate.
 
 == Usage
 
 Include 'nested_fields.js' in the layout for the Add and Remove behaviors.
 
+Declare accepts_nested_attributes_for each association. At present, nested_fields assumes that :allow_destroy is true.
+
 Use the nested_fields_for helper method.
-  <%= nested_fields_for form_builder, :pluralized_association_name, 'path_to/inner_partial' %>
+  <%= nested_fields_for form_builder, :pluralized_association_name %>
+
+For example, where f is a the builder for an object which +has_many+ +:associates+
+  <%= nested_fields_for f, :associates %>
 
 The same type of the form builder argument (e.g. Formtastic, SimpleForm, etc.) will automatically be used for the nested fields.
 
-The <tt>nested_fields_ready</tt> custom event is fired after a nested fieldset is (dynamically or otherwise) added.
+=== Options
+
+An optional block can be passed which will be displayed as a header.
+  <% nested_fields_for f, :associates do %>
+    ...
+  <% end %>
+
+==== :nested_partial
+
+By default, nested_fields will look for a partial in app/views/associates/_fields.html.erb. This can be overridden with the :nested_partial option.
+  <%= nested_fields_for f, :associates, :nested_partial => 'path_to/partial.html.erb' %>
+
+==== :legend
+
+By default, nested_fields will provide a +fieldset+ +legend+ with the pluralized, titleized name of the associate class. This can be overriden with the :legend option.
+  <%= nested_fields_for f, :associates, :legend => 'My Title' %>
+
+==== +:positioned_by+
+
+The +:positioned_by+ option takes in the name of a field which is used for positioning (e.g. acts_as_list). It will cause the association's +fieldset+ to have the +.positioned+ class and a +data-positioned-by+ attribute with the value.
+
+A javascript function is provided which sets the values of existing (non-removed) inputs which have id's ending in the value in the order they are displayed.
+
+  repositionNestedFields(nested_fieldset, position_field)
+
+=== Triggers
+
+The +nested_fields_changed+ custom event is fired by a nested associate's div after being dynamically added/removed.
+
+== Example
+
+Access {demonstration code}[https://github.com/jrmurad/nested_fields-example].
 
 == Credits
 

data/VERSION

@@ -1 +1 @@
-0.3.0
+0.4.0

data/app/views/nested_fields/_block.html.erb

@@ -2,7 +2,10 @@
   <a href="#" class="remove_nested_fields">Remove</a>
 
   <div class="nested_fields_inputs">
-    <%= render nested_partial, :f => f %>
-    <%= f.hidden_field :_destroy %>
+    <%= render :partial => nested_partial,
+               :object => f.object,
+               :as => f.object.class.name.underscore.to_sym,
+               :locals => {:f => f} %>
+    <%= f.hidden_field :_destroy, :class => :nested_fields_destroy %>
   </div>
 <% end %>

data/app/views/nested_fields/_singular_nested_fieldset.html.erb

@@ -9,10 +9,13 @@
       Has <%= association.to_s.titleize %>?
     </label>
 
-    <%= nested_f.hidden_field :_destroy, :class => :destroy_nested_one, :value => local_assigns[:has_zero] ? 'true' : 'false' %>
+    <%= nested_f.hidden_field :_destroy, :class => :destroy_nested_one, :value => local_assigns[:has_zero] %>
 
     <%= content_tag :div, :class => :nested_one, :style => ('display:none' if local_assigns[:has_zero]) do %>
-      <%= render nested_partial, :f => nested_f %>
+      <%= render :partial => nested_partial,
+                :object => nested_f.object,
+                :as => nested_f.object.class.name.underscore.to_sym,
+                :locals => {:f => nested_f} %>
     <% end %>
   <% end %>
 </fieldset>

data/nested_fields.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{nested_fields}
-  s.version = "0.3.0"
+  s.version = "0.4.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Jason Murad"]
-  s.date = %q{2011-02-13}
+  s.date = %q{2011-02-16}
   s.description = %q{Unobtrusive dynamic nested forms}
   s.email = %q{jason@thriess.com}
   s.extra_rdoc_files = [

data/public/javascripts/nested_fields.js

@@ -1,49 +1,34 @@
-$(document).ready(function() {
-  $('.nested_fieldset').each(function(i, nf) {
-    $(nf).trigger('nested_fields_ready');
-  });
-});
-
-$('.add_nested_fields').live('click', function() {
+$('a.add_nested_fields').live('click', function() {
   $.ajax({
     context: this,
     dataType: 'html',
     url: this.getAttribute('data-url'),
     success: function(content) {
       $(this).after(content);
-      $(this).trigger('nested_fields_ready');
+      $(this).trigger('nested_fields_changed');
     }
   });
 
   return false;
 });
 
-$('.remove_nested_fields').live('click', function() {
-  $(this).closest('div.nested_fields').find('input[type=hidden]').val('1');
-  $(this).closest('div.nested_fields').hide();
+$('a.remove_nested_fields').live('click', function() {
+  $(this).closest('div.nested_fields').hide().find('input[type=hidden].nested_fields_destroy').val('1');
+  $(this).closest('.nested_fieldset').trigger('nested_fields_changed');
   return false;
 });
 
-$('.nested_fields_has_one').live('change', function() {
-  var hidden_field = $(this).closest('.nested_fieldset').find('.destroy_nested_one');
-  $(hidden_field).val($(hidden_field).val() == 'true' ? 'false' : 'true');
-  $(this).closest('.nested_fieldset').find('.nested_one').toggle();
+$('input[type=checkbox].nested_fields_has_one').live('change', function() {
+  var hidden_field = $(this).closest('.nested_fieldset').find('input[type=hidden].destroy_nested_one');
+  $(hidden_field).val( $(hidden_field).val() == '' ? 1 : '' );
+  var nfs = $(this).closest('.nested_fieldset')
+  nfs.find('.nested_one').toggle();
+  nfs.trigger('nested_fields_changed')
 });
 
-function reposition(nested_fieldset, pos_fld) {
-  $(nested_fieldset).find('> .nested_fields').each(function(i, nested_fields) {
+/* reset position inputs to reflect addition or removal of associates */
+function repositionNestedFields(nested_fieldset, pos_fld) {
+  $(nested_fieldset).children('.nested_fields:visible').each(function(i, nested_fields) {
     $(nested_fields).find('input[id$="' + pos_fld + '"]').val(i);
   });
 }
-
-$('fieldset.positioned').live('nested_fields_ready', function() {
-  var pos_fld = this.getAttribute('data-positioned-by');
-
-  if (pos_fld) {
-    reposition(this, pos_fld);
-
-    if (!$(this).hasClass('ui-sortable')) {
-      $(this).sortable({update: function() { reposition(this, pos_fld); }});
-    }
-  }
-});

metadata

@@ -2,7 +2,7 @@
 name: nested_fields
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors: 
 - Jason Murad
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-02-13 00:00:00 -05:00
+date: 2011-02-16 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -98,7 +98,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: -167820414298998814
+      hash: -1830066020513997953
       segments: 
       - 0
       version: "0"