giraffesoft-attribute_fu 0.2

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 James Golick
+
+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

@@ -0,0 +1,115 @@
+= AttributeFu
+
+
+Creating multi-model forms is amazingly easy with AttributeFu.
+
+= Get It!
+
+  $ piston import http://svn.jamesgolick.com/attribute_fu/tags/stable vendor/plugins/attribute_fu
+
+= Conventions
+
+attribute_fu requires the fewest keystrokes if you follow certain conventions.
+
+* The partial that contains your associated model's form is expected to be called _class_name.template_ext
+  (e.g. the partial for your Task model would be called _task.html.erb)
+* The DOM element that contains the form for your model should have the CSS class .class_name
+  (e.g. the CSS class for your Task would be .task)
+* The DOM element that contains all of the rendered forms should have the DOM ID #class_name
+  (e.g. the DOM ID of the container of your Task forms would be #tasks)
+  <i>Note: This is only relevant if using the add_associated_link method.</i>
+
+= Example
+
+In this example, you'll build a form for a Project model, in which a list of associated (has_many) tasks can be edited. 
+
+The first thing you need to do is enable attributes on the association.
+  
+  class Project < ActiveRecord::Base
+    has_many :tasks, :attributes => true
+  end
+
+Instances of Project will now respond to task_attributes, whose format is as follows:
+  
+  @project.task_attributes = {
+    @project.tasks.first.id => {:title => "A new title for an existing task"},
+    :new => {
+      "0" => {:title => "A new task"}
+    }
+  }
+  
+Any tasks that already exist in that collection, and are not included in the hash, as supplied to task_attributes, will be removed from the association when saved. Most of the time, the form helpers should take care of building that hash for you, though.
+
+== Form Helpers
+
+If you follow certain conventions, rendering your associated model's form elements is incredibly simple. The partial should have the name of the associated element's type, and look like a regular old form partial (no messy fields_for calls, or any nonsense like that).
+  
+  ## _task.html.erb
+  <div class="task">
+    <label>Title</label>
+    <%= f.text_field :title %>
+  </div>
+
+Then, in your parent element's form, call the render_associated_form method on the form builder, with the collection of elements you'd like to render as the only argument.
+
+  ## _form.html.erb
+  <%= f.render_associated_form(@project.tasks) %>
+  
+That call will render the partial named _task.html.erb with each element in the supplied collection of tasks, wrapping the partial in a form builder (fields_for) with all the necessary arguments to produce a hash that will satisfy the task_attributes method.
+
+You may want to add a few blank tasks to the bottom of your form; no need to do that in the controller anymore.
+
+  <%= f.render_associated_form(@project.tasks, :new => 3) %>
+  
+Since this is Web2.0, no form would be complete without some DHTML add and remove buttons. Fortunately, there are some nifty helpers to create them for us. Simply calling remove_link on the form builder in your _task partial will do the trick.
+
+  ## _task.html.erb
+  <div class="task">
+    <label>Title</label>
+    <%= f.text_field :title %>
+    <%= f.remove_link "remove" %>
+  </div>
+  
+Creating the add button is equally simple. The add_associated_link helper will do all of the heavy lifting for you.
+
+  ## _form.html.erb
+  <%= f.add_associated_link "Add New Task", @project.tasks.build %>
+  
+That's all you have to do to create a multi-model form with attribute_fu!
+
+== Discarding Blank Child Models
+
+If you want to show a bunch of blank child model forms at the bottom of your form, but you only want to save the ones that are filled out, you can use the discard_if option. It accepts either a proc:
+
+  class Project < ActiveRecord::Base
+    has_many :tasks, :attributes => true, :discard_if => proc { |task| task.title.blank? }
+  end
+
+...or a symbol...
+
+  class Project < ActiveRecord::Base
+    has_many :tasks, :attributes => true, :discard_if => :blank?
+  end
+  
+  class Task < ActiveRecord::Base
+    def blank?
+      title.blank?
+    end
+  end
+
+Using a symbol allows you to keep code DRYer if you are using that routine in more than one place. Both of those examples, however, would have the same effect.
+
+= Updates
+
+Come join the discussion on the {mailing list}[link:http://groups.google.com/group/attribute_fu]
+
+Updates will be available {here}[http://jamesgolick.com/attribute_fu]
+
+
+== Credits
+
+attribute_fu was created, and is maintained by {James Golick}[http://jamesgolick.com].
+
+
+
+Copyright (c) 2007 James Golick, GiraffeSoft Inc., released under the MIT license

data/Rakefile

@@ -0,0 +1,22 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the attribute_fu plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the attribute_fu plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'AttributeFu'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/init.rb

@@ -0,0 +1,2 @@
+ActiveRecord::Base.class_eval { include AttributeFu::Associations }
+ActionView::Helpers::FormBuilder.class_eval { include AttributeFu::AssociatedFormHelper }

data/lib/attribute_fu.rb

@@ -0,0 +1,2 @@
+module AttributeFu #:nodoc:  
+end

data/lib/attribute_fu/associated_form_helper.rb

@@ -0,0 +1,139 @@
+module AttributeFu
+  # Methods for building forms that contain fields for associated models.
+  #
+  # Refer to the Conventions section in the README for the various expected defaults.
+  #
+  module AssociatedFormHelper
+    # Works similarly to fields_for, but used for building forms for associated objects.
+    # 
+    # Automatically names fields to be compatible with the association_attributes= created by attribute_fu.
+    #
+    # An options hash can be specified to override the default behaviors.
+    #
+    # Options are:
+    # <tt>:javascript</tt>  - Generate id placeholders for use with Prototype's Template class (this is how attribute_fu's add_associated_link works). 
+    # <tt>:name</tt>        - Specify the singular name of the association (in singular form), if it differs from the class name of the object.
+    #
+    # Any other supplied parameters are passed along to fields_for.
+    # 
+    # Note: It is preferable to call render_associated_form, which will automatically wrap your form partial in a fields_for_associated call.
+    #
+    def fields_for_associated(associated, *args, &block)
+      conf            = args.last.is_a?(Hash) ? args.last : {}
+      associated_name = extract_option_or_class_name(conf, :name, associated)
+      name            = associated_base_name associated_name
+      
+      unless associated.new_record?
+        name << "[#{associated.new_record? ? 'new' : associated.id}]"
+      else
+        @new_objects ||= {}
+        @new_objects[associated_name] ||= -1 # we want naming to start at 0
+        identifier = !conf.nil? && conf[:javascript] ? '#{number}' : @new_objects[associated_name]+=1
+        
+        name << "[new][#{identifier}]"
+      end
+      
+      @template.fields_for(name, *args.unshift(associated), &block)
+    end
+    
+    # Creates a link for removing an associated element from the form, by removing its containing element from the DOM.
+    #
+    # Must be called from within an associated form.
+    #     
+    # An options hash can be specified to override the default behaviors.
+    #
+    # Options are:
+    # * <tt>:selector</tt>  - The CSS selector with which to find the element to remove.
+    # * <tt>:function</tt>  - Additional javascript to be executed before the element is removed.
+    #
+    # Any remaining options are passed along to link_to_function
+    #
+    def remove_link(name, *args)
+      options = args.extract_options!
+
+      css_selector = options.delete(:selector) || ".#{@object.class.name.split("::").last.underscore}"
+      function     = options.delete(:function) || ""
+      
+      function << "$(this).up('#{css_selector}').remove()"
+      
+      @template.link_to_function(name, function, *args.push(options))
+    end
+    
+    # Creates a link that adds a new associated form to the page using Javascript.
+    #
+    # Must be called from within an associated form.
+    #
+    # Must be provided with a new instance of the associated object.
+    #
+    #   e.g. f.add_associated_link 'Add Task', @project.tasks.build
+    #
+    # An options hash can be specified to override the default behaviors.
+    #
+    # Options are:
+    # * <tt>:partial</tt>    - specify the name of the partial in which the form is located.
+    # * <tt>:container</tt>  - specify the DOM id of the container in which to insert the new element.
+    # * <tt>:expression</tt> - specify a javascript expression with which to select the container to insert the new form in to (i.e. $(this).up('.tasks'))
+    # * <tt>:name</tt>       - specify an alternate class name for the associated model (underscored)
+    #
+    # Any additional options are forwarded to link_to_function. See its documentation for available options.
+    #
+    def add_associated_link(name, object, opts = {})
+      associated_name  = extract_option_or_class_name(opts, :name, object)
+      variable         = "attribute_fu_#{associated_name}_count"
+      
+      opts.symbolize_keys!
+      partial          = opts.delete(:partial)    || associated_name
+      container        = opts.delete(:expression) || "'#{opts.delete(:container) || associated_name.pluralize}'"
+      
+      form_builder     = self # because the value of self changes in the block
+      
+      @template.link_to_function(name, opts) do |page|
+        page << "if (typeof #{variable} == 'undefined') #{variable} = 0;"
+        page << "new Insertion.Bottom(#{container}, new Template("+form_builder.render_associated_form(object, :fields_for => { :javascript => true }, :partial => partial).to_json+").evaluate({'number': --#{variable}}))"
+      end
+    end
+    
+    # Renders the form of an associated object, wrapping it in a fields_for_associated call.
+    #
+    # The associated argument can be either an object, or a collection of objects to be rendered.
+    #
+    # An options hash can be specified to override the default behaviors.
+    # 
+    # Options are:
+    # * <tt>:new</tt>        - specify a certain number of new elements to be added to the form. Useful for displaying a 
+    #   few blank elements at the bottom.
+    # * <tt>:name</tt>       - override the name of the association, both for the field names, and the name of the partial
+    # * <tt>:partial</tt>    - specify the name of the partial in which the form is located.
+    # * <tt>:fields_for</tt> - specify additional options for the fields_for_associated call
+    # * <tt>:locals</tt>     - specify additional variables to be passed along to the partial
+    # * <tt>:render</tt>     - specify additional options to be passed along to the render :partial call
+    #
+    def render_associated_form(associated, opts = {})
+      associated = associated.is_a?(Array) ? associated : [associated] # preserve association proxy if this is one
+      
+      opts.symbolize_keys!
+      (opts[:new] - associated.select(&:new_record?).length).times { associated.build } if opts[:new]
+
+      unless associated.empty?
+        name              = extract_option_or_class_name(opts, :name, associated.first)
+        partial           = opts[:partial] || name
+        local_assign_name = partial.split('/').last.split('.').first
+
+        associated.map do |element|
+          fields_for_associated(element, (opts[:fields_for] || {}).merge(:name => name)) do |f|
+            @template.render({:partial => "#{partial}", :locals => {local_assign_name.to_sym => element, :f => f}.merge(opts[:locals] || {})}.merge(opts[:render] || {}))
+          end
+        end
+      end
+    end
+    
+    private
+      def associated_base_name(associated_name)
+        "#{@object_name}[#{associated_name}_attributes]"
+      end
+      
+      def extract_option_or_class_name(hash, option, object)
+        (hash.delete(option) || object.class.name.split('::').last.underscore).to_s
+      end
+  end
+end

data/lib/attribute_fu/associations.rb

@@ -0,0 +1,124 @@
+module AttributeFu
+  module Associations #:nodoc:
+    
+    def self.included(base) #:nodoc:
+      base.class_eval do
+        extend ClassMethods
+        class << self; alias_method_chain :has_many, :association_option; end
+        
+        class_inheritable_accessor  :managed_association_attributes
+        write_inheritable_attribute :managed_association_attributes, {}
+        
+        after_update :save_managed_associations
+      end
+    end
+    
+    def method_missing(method_name, *args) #:nodoc:
+      if method_name.to_s =~ /.+?\_attributes=/
+        association_name = method_name.to_s.gsub '_attributes=', ''
+        association      = managed_association_attributes.keys.detect { |element| element == association_name.to_sym } || managed_association_attributes.keys.detect { |element| element == association_name.pluralize.to_sym }
+        
+        unless association.nil?
+          has_many_attributes association, args.first
+          
+          return
+        end
+      end
+      
+      super
+    end
+    
+    private
+      def has_many_attributes(association_id, attributes) #:nodoc:
+        association = send(association_id)
+        attributes = {} unless attributes.is_a? Hash
+
+        attributes.symbolize_keys!
+        
+        if attributes.has_key?(:new)
+          new_attrs = attributes.delete(:new)
+          new_attrs = new_attrs.sort do |a,b|
+            value = lambda { |i| i < 0 ? i.abs + new_attrs.length : i }
+            
+            value.call(a.first.to_i) <=> value.call(b.first.to_i)
+          end
+          new_attrs.each { |i, new_attrs| association.build new_attrs } 
+        end
+        
+        attributes.stringify_keys!        
+        instance_variable_set removal_variable_name(association_id), association.reject { |object| object.new_record? || attributes.has_key?(object.id.to_s) }.map(&:id)
+        attributes.each do |id, object_attrs|
+          object = association.detect { |associated| associated.id.to_s == id }
+          object.attributes = object_attrs unless object.nil?
+        end
+        
+        # discard blank attributes if discard_if proc exists
+        unless (discard = managed_association_attributes[association_id][:discard_if]).nil?
+          association.reject! { |object| object.new_record? && discard.call(object) }
+          association.delete(*association.select { |object| discard.call(object) })
+        end
+      end
+      
+      def save_managed_associations #:nodoc:
+        if managed_association_attributes != nil
+          managed_association_attributes.keys.each do |association_id|
+            association = send(association_id)
+            association.each(&:save)
+
+            unless (objects_to_remove = instance_variable_get removal_variable_name(association_id)).nil?
+              objects_to_remove.each { |remove_id| association.delete association.detect { |obj| obj.id.to_s == remove_id.to_s } }
+              instance_variable_set removal_variable_name(association_id), nil
+            end
+          end
+        end
+      end
+      
+      def removal_variable_name(association_id) #:nodoc:
+        "@#{association_id.to_s.pluralize}_to_remove"
+      end
+    
+    module ClassMethods
+      
+      # Behaves identically to the regular has_many, except adds the option <tt>:attributes</tt>, which, if true, creates
+      # a method called association_id_attributes (i.e. task_attributes, or comment_attributes) for setting the attributes
+      # of a collection of associated models. 
+      #
+      # It also adds the option <tt>:discard_if</tt>, which accepts a proc or a symbol. If the proc evaluates to true, the 
+      # child model will be discarded. The symbol is sent as a message to the child model instance; if it returns true,
+      # the child model will be discarded.
+      # 
+      # e.g.
+      #
+      #   :discard_if => proc { |comment| comment.title.blank? }
+      #     or
+      #   :discard_if => :blank? # where blank is defined in Comment
+      #  
+      #
+      # The format is as follows:
+      #
+      #     @project.task_attributes = {
+      #       @project.tasks.first.id => {:title => "A new title for an existing task"},
+      #       :new => {
+      #         "0" => {:title => "A new task"}
+      #       }
+      #     }
+      #
+      # Any existing tasks that are not present in the attributes hash will be removed from the association when the (parent) model
+      # is saved.
+      #
+      def has_many_with_association_option(association_id, options = {}, &extension)
+        unless (config = options.delete(:attributes)).nil?
+          managed_association_attributes[association_id] = {}
+          if options.has_key?(:discard_if)
+            discard_if = options.delete(:discard_if)
+            discard_if = discard_if.to_proc if discard_if.is_a?(Symbol)
+            managed_association_attributes[association_id][:discard_if] = discard_if
+          end
+        end
+        
+        has_many_without_association_option(association_id, options, &extension)
+      end
+    end
+    
+  end # Associations
+end # AttributeFu

data/tasks/attribute_fu_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :attribute_fu do
+#   # Task goes here
+# end

data/test/Rakefile

@@ -0,0 +1,10 @@
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require(File.join(File.dirname(__FILE__), 'config', 'boot'))
+
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+require 'tasks/rails'