freeform 0.0.2 → 0.0.3.rc1

data/README.md

@@ -1,12 +1,12 @@
 # FreeForm
 
-FreeForm is a gem designed to give you total control over form objects, allowing you to map form objects to domain objects in any way that you see fit.
+FreeForm is a gem designed to give you total control over form objects, allowing you to map form objects to domain objects in any way that you see fit.  The primary benefits are:
+  * Decoupling form objects from domain models
+  * Allowing form-specific validations, while respecting model validations
+  * Simply composing multi-model forms
+  * Removing the ugliness of `accepts_nested_attributes_for`
 
-It is still a very-pre-beta work in progess, but hopefully it can showcase the power of form objects.
-
-FreeForm is designed primarily with Rails in mind, but it should work on any Ruby framework.
-
-FreeForm is compatible with (as far as I know) most form gems, including simpleform, formbuilder, and Ryan Bate's nested_form gem.
+FreeForm is designed primarily with Rails in mind, but it should work on any Ruby framework.  FreeForm is compatible with most form gems, including simpleform, formbuilder, and Ryan Bate's nested_form gem.
 
 ## Installation
 
@@ -107,6 +107,58 @@ end
 user = User.new
 RegistrationForm.new(:user => user, :address => user.build_address)
 ```
+## Assigning Parameters
+
+Forms can be populated either directly through accessors (e.g. `form.street = "123 Main St."`), or using the `assign_params()` or `fill()` methods.
+
+```ruby
+class RegistrationForm < FreeForm::Form
+  form_models :user, :address
+
+  property :username,              :on => :user
+  property :street,                :on => :address
+end
+
+form = RegistrationForm.new(:user => User.new, :address => Address.new)
+form.assign_params({ :username => "myusername", :street => "1600 Pennsylvania Ave." })
+# fill() is just an alias for assign_params
+form.fill({ :username => "myusername", :street => "1600 Pennsylvania Ave." })
+```
+
+## Saving & Marking For Destruction
+
+Calling `form.save` will validate the form, then make a save call to each model defined in the form (and each nested form).  A call to `save!` behaves the same way.
+
+```ruby
+class RegistrationForm < FreeForm::Form
+  form_models :user, :address
+
+  property :username,              :on => :user
+  property :street,                :on => :address
+end
+
+form = RegistrationForm.new(:user => User.new, :address => Address.new)
+form.fill({ :username => "myusername", :street => "1600 Pennsylvania Ave." })
+form.save # SAVES the User and Address models
+```
+
+Additionally, each model has a method you can add called `allow_destroy_on_save`.  This method adds an accessor called `_destroy` (also aliased as `marked_for_destruction`) that can be set.  If this is set, each form in the model will receive a `destroy` call on save.
+
+```ruby
+class RegistrationForm < FreeForm::Form
+  form_models :user, :address
+  allow_destroy_on_save
+
+  property :username,              :on => :user
+  property :street,                :on => :address
+end
+
+form = RegistrationForm.new(:user => User.new, :address => Address.new)
+form.fill({ :username => "myusername", :street => "1600 Pennsylvania Ave.", :_destroy => "1" })
+form.save # DESTROYS the User and Address models
+```
+This method is necessary if you use the nested_form gem for dynamically creating/deleting models.
+
 ## Form Validations
 
 FreeForm handles validations wherever you define them.  If you want to check model validations, simply specify that option in your form definition

data/lib/freeform/form/nested.rb

@@ -64,7 +64,7 @@ module FreeForm
           form_class = self.class.nested_forms[:"#{attribute}"]
           
           # Set default intializer if none provided
-          initializer ||= send("#{attribute}_form_initializer")
+          initializer ||= send("#{attribute}_form_initializer").call
 
           # Build new model
           form_model = form_class.new(initializer)

data/lib/freeform/form/property.rb

@@ -33,6 +33,12 @@ module FreeForm
         @ignored_blank_params ||= []
       end
 
+      def allow_destroy_on_save
+        # Define _destroy method for marked-for-destruction handling
+        attr_accessor :_destroy
+        alias_method :marked_for_destruction, :_destroy
+      end
+
       def property(attribute, options={})
         if options[:on]
           def_delegator options[:on], attribute

data/lib/freeform/form/{persistence.rb → validation.rb}

@@ -1,5 +1,5 @@
 module FreeForm
-  module Persistence
+  module Validation
     def self.included(base)
       base.extend(ClassMethods)
     end
@@ -9,30 +9,7 @@ module FreeForm
         validate :model_validity
       end
     end
-    
-    def save
-      return false unless valid?
-      self.class.models.each do |form_model|
-        if send(form_model).is_a?(Array)
-          send(form_model).each { |model| return model.save }
-        else
-          return false unless send(form_model).save
-        end
-      end
-      return true
-    end
-  
-    def save!
-      raise StandardError, "form invalid." unless valid?
-      self.class.models.each do |form_model|
-        if send(form_model).is_a?(Array)
-          send(form_model).each { |model| model.save! }
-        else
-          send(form_model).save!
-        end
-      end
-    end
-  
+      
     protected
     def model_validity
       model_validity = true

data/lib/freeform/form.rb

@@ -1,6 +1,10 @@
 require 'forwardable'
 require 'ostruct'
 require 'active_model'
+require 'freeform/form/form_input_key'
+require 'freeform/form/nested'
+require 'freeform/form/property'
+require 'freeform/form/validation'
 
 module FreeForm
   class Form
@@ -9,6 +13,10 @@ module FreeForm
     extend ActiveModel::Callbacks
     include ActiveModel::Conversion
     include ActiveModel::Validations
+    include FreeForm::FormInputKey
+    include FreeForm::Nested
+    include FreeForm::Property
+    include FreeForm::Validation
 
     # Instance Methods
     #----------------------------------------------------------------------------
@@ -20,5 +28,44 @@ module FreeForm
     def initialize(h={})
       h.each {|k,v| send("#{k}=",v)}
     end  
+    
+    def save
+      return false unless valid?
+      self.class.models.each do |form_model|
+        if send(form_model).is_a?(Array)
+          send(form_model).each { |model| return model.save }
+        else
+          if marked_for_destruction?
+            send(form_model).destroy
+          else
+            return false unless send(form_model).save
+          end
+        end
+      end
+      return true
+    end
+  
+    def save!
+      raise StandardError, "form invalid." unless valid?
+      self.class.models.each do |form_model|
+        if send(form_model).is_a?(Array)
+          send(form_model).each { |model| model.save! }
+        else
+          if marked_for_destruction?
+            send(form_model).destroy
+          else
+            send(form_model).save!
+          end
+        end
+      end
+    end    
+    
+    def marked_for_destruction?
+      if self.respond_to?(:_destroy)
+        return self._destroy
+      else
+        return false
+      end
+    end
   end
 end

data/lib/freeform/version.rb

@@ -1,3 +1,3 @@
 module Freeform
-  VERSION = "0.0.2"
+  VERSION = "0.0.3.rc1"
 end

data/lib/freeform.rb

@@ -1,14 +1,5 @@
 require 'freeform/version'
 require 'freeform/form'
-#require 'reform/form/composition'
-#require 'reform/form/active_model'
 
-if defined?(Rails) # DISCUSS: is everyone ok with this?
- # require 'reform/rails'
-end
-
-=begin
-module Freeform
-  # Your code goes here...
-end
-=end
+if defined?(Rails) # Where to include Rails specific modules...
+end

data/spec/acceptance_spec.rb

@@ -0,0 +1,309 @@
+require 'spec_helper'
+
+describe FreeForm::Form do
+  let(:user_class) do
+    Class.new(Module) do
+      include ActiveModel::Validations
+      def self.model_name; ActiveModel::Name.new(self, nil, "user") end
+
+      attr_accessor :username
+      attr_accessor :email
+      validates :username, :presence => true
+
+      def save; return valid? end
+      alias_method :save!, :save
+      def destroy; return true end
+    end
+  end
+
+  let(:address_class) do
+    Class.new(Module) do
+      include ActiveModel::Validations
+      def self.model_name; ActiveModel::Name.new(self, nil, "address") end
+
+      attr_accessor :street
+      attr_accessor :city
+      attr_accessor :state
+      validates :street, :presence => true
+      validates :city, :presence => true
+      validates :state, :presence => true
+
+      def save; return valid? end
+      alias_method :save!, :save
+      def destroy; return true end
+    end
+  end
+
+  let(:phone_class) do
+    Class.new(Module) do
+      include ActiveModel::Validations
+      def self.model_name; ActiveModel::Name.new(self, nil, "phone") end
+
+      attr_accessor :area_code
+      attr_accessor :number
+      validates :number, :presence => true
+
+      def save; return valid? end
+      alias_method :save!, :save
+      def destroy; return true end
+    end
+  end
+
+  let(:form_class) do
+    klass = Class.new(FreeForm::Form) do
+      form_input_key :user
+      form_models :user, :address
+      validate_models
+      allow_destroy_on_save
+      
+      property :username, :on => :user      
+      property :email,    :on => :user      
+      property :street, :on => :address      
+      property :city,   :on => :address      
+      property :state,  :on => :address      
+
+      has_many :phone_numbers do
+        form_model :phone
+        validate_models
+        allow_destroy_on_save
+        
+        property :area_code, :on => :phone
+        property :number,    :on => :phone
+      end
+    end
+    # This wrapper just avoids CONST warnings
+    v, $VERBOSE = $VERBOSE, nil
+      Module.const_set("AcceptanceForm", klass)
+    $VERBOSE = v
+    klass
+  end
+
+  let(:form) do
+    form_model = form_class.new( 
+      :user => user_class.new, 
+      :address => address_class.new,
+      :phone_numbers_form_initializer => lambda { { :phone => phone_class.new } }
+      )
+    form_model.build_phone_number
+    form_model
+  end
+
+  describe "form initialization", :initialization => true do
+    it "initializes with user model" do
+      form.user.should be_a(user_class)
+    end
+
+    it "initializes with address model" do
+      form.address.should be_a(address_class)
+    end
+
+    it "initializes with phone model" do
+      form.phone_numbers.first.phone.should be_a(phone_class)
+    end
+  end
+
+  describe "building nested models", :nested_models => true do
+    it "can build multiple phone_numbers" do
+      form.phone_numbers.count.should eq(1)
+      form.build_phone_number
+      form.build_phone_number
+      form.phone_numbers.count.should eq(3)
+    end
+
+    it "build new models for each phone numbers" do
+      form.build_phone_number
+      phone_1 = form.phone_numbers.first.phone
+      phone_2 = form.phone_numbers.last.phone
+      phone_1.should_not eq(phone_2)
+    end
+  end
+
+  describe "assigning parameters", :assign_params => true do
+    let(:attributes) do {
+      :username => "dummyuser",
+      :email => "test@email.com",
+      :street => "1 Maple St.",
+      :city => "Portland",
+      :state => "Oregon",
+      :phone_numbers_attributes => {
+        "0" => {
+          :area_code => "555",
+          :number => "123-4567"
+        },
+        "1" => {
+          :area_code => "202",
+          :number => "876-5432"
+        }
+      } }
+    end
+    
+    before(:each) do
+      form.fill(attributes)
+    end
+    
+    it "assigns username" do
+      form.username.should eq("dummyuser")
+    end
+
+    it "assigns street" do
+      form.street.should eq("1 Maple St.")
+    end
+
+    it "assigns phone number area code" do
+      form.phone_numbers.first.phone.area_code.should eq("555")
+    end
+
+    it "builds new phone number automatically" do
+      form.phone_numbers.count.should eq(2)
+    end
+
+    it "assigns second phone number area code" do
+      form.phone_numbers.last.phone.area_code.should eq("202")
+    end
+  end
+
+  describe "validations", :validations => true do
+    context "with invalid attributes" do
+      let(:attributes) do {
+        :username => "dummyuser",
+        :email => "test@email.com",
+        :street => nil,
+        :city => "Portland",
+        :state => "Oregon",
+        :phone_numbers_attributes => {
+          "0" => {
+            :number => "123-4567"
+          },
+          "1" => {
+            :area_code => "202"
+          }
+        } }
+      end
+      
+      before(:each) do
+        form.fill(attributes)
+        form.valid?
+      end
+      
+      it "should be invalid" do
+        form.should_not be_valid
+      end
+
+      it "should have errors on street" do
+        form.errors[:street].should eq(["can't be blank"])
+      end
+
+      it "should have errors on first phone number's area code" do
+        form.phone_numbers.first.errors[:area_code].should be_empty
+      end
+
+      it "should have errors on first phone number's number" do
+        form.phone_numbers.last.errors[:number].should eq(["can't be blank"])
+      end
+
+      it "should return false on 'save'" do
+        form.save.should be_false
+      end
+
+      it "should raise error on 'save!'" do
+        expect{ form.save!.should be_false }.to raise_error
+      end
+    end
+
+    context "with valid attributes" do
+      let(:attributes) do {
+        :username => "dummyuser",
+        :email => "test@email.com",
+        :street => "1 Maple St.",
+        :city => "Portland",
+        :state => "Oregon",
+        :phone_numbers_attributes => {
+          "0" => {
+            :area_code => "555",
+            :number => "123-4567"
+          },
+          "1" => {
+            :area_code => "202",
+            :number => "876-5432"
+          }
+        } }
+      end
+      
+      before(:each) do
+        form.fill(attributes)
+      end
+      
+      it "should be valid" do
+        form.should be_valid
+      end
+
+      it "should return true on 'save', and call save on other models" do
+        form.user.should_receive(:save).and_return(true)
+        form.address.should_receive(:save).and_return(true)
+        form.phone_numbers.first.phone.should_receive(:save).and_return(true)
+        form.save
+      end
+
+      it "should return true on 'save!', and call save! on other models" do
+        form.user.should_receive(:save!).and_return(true)
+        form.address.should_receive(:save!).and_return(true)
+        form.phone_numbers.first.phone.should_receive(:save!).and_return(true)
+        form.save!
+      end
+      
+      describe "destroying on save", :destroy_on_save => true do
+        describe "save" do
+          it "destroys models on save if set" do
+            form._destroy = true
+            form.user.should_receive(:destroy).and_return(true)
+            form.address.should_receive(:destroy).and_return(true)
+            form.phone_numbers.first.phone.should_receive(:save).and_return(true)
+            form.save
+          end
+    
+          it "destroys models on save if set through attribute" do
+            form.fill({:_destroy => "1"})
+            form.user.should_receive(:destroy).and_return(true)
+            form.address.should_receive(:destroy).and_return(true)
+            form.phone_numbers.first.phone.should_receive(:save).and_return(true)
+            form.save
+          end
+
+          it "destroys nested models on save if set" do
+            form.phone_numbers.first._destroy = true
+            form.user.should_receive(:save).and_return(true)
+            form.address.should_receive(:save).and_return(true)
+            form.phone_numbers.first.phone.should_receive(:destroy).and_return(true)
+            form.save
+          end
+        end
+        
+        describe "save!" do
+          it "destroys models on save! if set" do
+            form._destroy = true
+            form.user.should_receive(:destroy).and_return(true)
+            form.address.should_receive(:destroy).and_return(true)
+            form.phone_numbers.first.phone.should_receive(:save!).and_return(true)
+            form.save!
+          end
+  
+          it "destroys models on save! if set" do
+            form.fill({:_destroy => "1"})
+            form.user.should_receive(:destroy).and_return(true)
+            form.address.should_receive(:destroy).and_return(true)
+            form.phone_numbers.first.phone.should_receive(:save!).and_return(true)
+            form.save!
+          end
+
+          it "destroys nested models on save! if set" do
+            form.phone_numbers.first._destroy = true
+            form.user.should_receive(:save!).and_return(true)
+            form.address.should_receive(:save!).and_return(true)
+            form.phone_numbers.first.phone.should_receive(:destroy).and_return(true)
+            form.save!
+          end
+        end
+      end
+    end
+  end
+end

data/spec/form/nested_spec.rb

@@ -28,7 +28,9 @@ describe FreeForm::Nested do
       end
   
       let(:form) do
-        form_class.new( :mailing_address_form_initializer => { :address => OpenStruct.new } )
+        form_model = form_class.new( 
+          :mailing_address_form_initializer => lambda { { :address => OpenStruct.new } } 
+        )
       end
 
       describe "form class" do
@@ -49,6 +51,16 @@ describe FreeForm::Nested do
           form.mailing_addresses.first.should be_a(Module::DummyForm::MailingAddressesForm)
         end
 
+        it "builds unique models" do
+          # Using module here, since they initialize uniquely
+          form.mailing_address_form_initializer = lambda { { :address => Module.new } } 
+          form.build_mailing_address
+          form.build_mailing_address
+          address_1 = form.mailing_addresses.first.address
+          address_2 = form.mailing_addresses.last.address
+          address_1.should_not eq(address_2)
+        end
+
         it "allows nested_forms to be built with custom initializers" do
           form.build_mailing_address(:address => OpenStruct.new(:street => "1600 Pennsylvania Ave."))
           form.mailing_addresses.first.street.should eq("1600 Pennsylvania Ave.")

data/spec/form/{persistence_spec.rb → validation_spec.rb}

@@ -1,9 +1,9 @@
 require 'spec_helper'
 require 'freeform/form/property'
 require 'freeform/form/nested'
-require 'freeform/form/persistence'
+require 'freeform/form/validation'
 
-describe FreeForm::Persistence do
+describe FreeForm::Validation do
   let(:user) do
     model = Class.new(Module) do
       include ActiveModel::Validations
@@ -34,13 +34,13 @@ describe FreeForm::Persistence do
   end
 
   describe "validation", :validation => true do    
-    context "without model validation" do
+    context "without model validation", :no_model_validation => true do
       let(:form_class) do
         klass = Class.new(Module) do
           include ActiveModel::Validations
           include FreeForm::Property
           include FreeForm::Nested
-          include FreeForm::Persistence
+          include FreeForm::Validation
 
           form_model :user
           property :username, :on => :user
@@ -64,7 +64,9 @@ describe FreeForm::Persistence do
       end
   
       let(:form) do
-        test_form = form_class.new( :user => OpenStruct.new, :address_form_initializer => { :address => OpenStruct.new } )
+        test_form = form_class.new( 
+          :user => user, 
+          :address_form_initializer => lambda { { :address => address } } )
         test_form.build_address
         test_form
       end
@@ -84,13 +86,13 @@ describe FreeForm::Persistence do
       end
     end
 
-    context "with model validation" do
+    context "with model validation", :model_validation => true do
       let(:form_class) do
         klass = Class.new(Module) do
           include ActiveModel::Validations
           include FreeForm::Property
           include FreeForm::Nested
-          include FreeForm::Persistence
+          include FreeForm::Validation
           validate_models
 
           form_model :user
@@ -102,7 +104,7 @@ describe FreeForm::Persistence do
             include ActiveModel::Validations
             include FreeForm::Property
             include FreeForm::Nested
-            include FreeForm::Persistence
+            include FreeForm::Validation
             validate_models
             declared_model :address
             
@@ -122,7 +124,9 @@ describe FreeForm::Persistence do
       end
   
       let(:form) do
-        test_form = form_class.new( :user => user, :address_form_initializer => { :address => address } )
+        test_form = form_class.new( 
+          :user => user, 
+          :address_form_initializer => lambda { { :address => address } } )
         test_form.build_address
         test_form
       end
@@ -147,91 +151,4 @@ describe FreeForm::Persistence do
       end
     end
   end
-
-  describe "saving", :saving => true do
-    let(:form_class) do
-      klass = Class.new(Module) do
-        include ActiveModel::Validations
-        include FreeForm::Property
-        include FreeForm::Nested
-        include FreeForm::Persistence
-        validate_models
-
-        form_model :user
-        property :username, :on => :user
-        property :form_property
-        validates :form_property, :presence => true
-        
-        nested_form :addresses do
-          include ActiveModel::Validations
-          include FreeForm::Property
-          include FreeForm::Nested
-          include FreeForm::Persistence
-          validate_models
-          declared_model :address
-          
-          property :street, :on => :address
-          property :city, :on => :address
-        end
-        
-        def initialize(h={})
-          h.each {|k,v| send("#{k}=",v)}
-        end  
-      end
-      # This wrapper just avoids CONST warnings
-      v, $VERBOSE = $VERBOSE, nil
-        Module.const_set("DummyForm", klass)
-      $VERBOSE = v
-      klass
-    end
-
-    let(:form) do
-      test_form = form_class.new( :user => user, :address_form_initializer => { :address => address } )
-      test_form.build_address
-      test_form
-    end
-    
-    context "form is invalid" do
-      it "should be invalid" do
-        form.should_not be_valid
-      end
-
-      it "should return false on 'save'" do
-        form.save.should be_false
-      end
-
-      it "should raise error on 'save!'" do
-        expect{ form.save!.should be_false }.to raise_error
-      end
-    end
-
-    context "form is valid" do
-      before(:each) do
-        form.fill({
-          :username => "myusername",
-          :form_property => "present",
-          :addresses_attributes => { "0" => {
-            :street => "123 Main St.",
-            :city => "Springfield"
-          } }
-        })
-      end
-
-      it "should be valid" do
-        form.should be_valid
-      end
-
-      it "should return true on 'save', and call save on other models" do
-        user.should_receive(:save).and_return(true)
-        address.should_receive(:save).and_return(true)
-        form.save.should be_true
-      end
-
-      it "should return true on 'save!', and call save! on other models" do
-        user.should_receive(:save!).and_return(true)
-        address.should_receive(:save!).and_return(true)
-        form.save!.should be_true
-      end
-    end
-  end
 end

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: freeform
 version: !ruby/object:Gem::Version
-  version: 0.0.2
-  prerelease: 
+  version: 0.0.3.rc1
+  prerelease: 6
 platform: ruby
 authors:
 - brycesenz
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-11-14 00:00:00.000000000 Z
+date: 2013-11-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -94,13 +94,14 @@ files:
 - lib/freeform/form.rb
 - lib/freeform/form/form_input_key.rb
 - lib/freeform/form/nested.rb
-- lib/freeform/form/persistence.rb
 - lib/freeform/form/property.rb
+- lib/freeform/form/validation.rb
 - lib/freeform/version.rb
+- spec/acceptance_spec.rb
 - spec/form/form_input_key_spec.rb
 - spec/form/nested_spec.rb
-- spec/form/persistence_spec.rb
 - spec/form/property_spec.rb
+- spec/form/validation_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/brycesenz/freeform
 licenses:
@@ -118,9 +119,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
-  - - ! '>='
+  - - ! '>'
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.25
@@ -129,8 +130,9 @@ specification_version: 3
 summary: FreeForm lets you compose forms however you like, explicitly guiding how
   each field maps back to your domain models.  No more accepting nested attributes!
 test_files:
+- spec/acceptance_spec.rb
 - spec/form/form_input_key_spec.rb
 - spec/form/nested_spec.rb
-- spec/form/persistence_spec.rb
 - spec/form/property_spec.rb
+- spec/form/validation_spec.rb
 - spec/spec_helper.rb