reform 1.2.0.beta2 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7d54671e9b119dc5bbe6b8b405c0f2f947a3004b
-  data.tar.gz: bc1ed19c08fd3f91435cc4b20e512fc9c34262c5
+  metadata.gz: d8d0dc76658a132e15bea8612f35e7bfa77fb7b8
+  data.tar.gz: 31226f61d63c42b0a641b5592eb9714cb29bcff2
 SHA512:
-  metadata.gz: 7a53b1ec82dca50a28734ad805a0555e30e2c9d403d0e9ca51765bceffe19cf32f325f20ed7b2356853463053aff56d1953b1eca027a3936cd877840a248f63d
-  data.tar.gz: ca494adb0607285f727a3562609526c06ad9f4fb0ff25143395731db5d9ad17dec892ba14bf7dadc58f27ab5deaee468947bd61c679ce80a32b43cb90d97ddbd
+  metadata.gz: cde409c7fa9dc9054d05e2dafb7cf672abf8585d85b97f05f8f0d37b0d6c0de25e554775fb7a8a5eec57567977ba8ff03cdcb2276190c964e5f62c31259ce027
+  data.tar.gz: 70ac7b9421a13e0936ba9e149f611ad9f540b071f1f557d474a191c9c1d4a7e2a8fc126a9510a7fed65b1ef70078033ea4e8f34a6d9d2bc3dd9b74fbc61bd1c3

data/.travis.yml

@@ -1,9 +1,10 @@
 language: ruby
 rvm:
+  - 2.1.4
   - 2.0.0
   - 1.9.3
 gemfile:
   - gemfiles/Gemfile.rails-4.0
   - gemfiles/Gemfile.rails-3.2
   - gemfiles/Gemfile.rails-3.1
-  - gemfiles/Gemfile.rails-3.0
+  - gemfiles/Gemfile.rails-3.0

data/CHANGES.md

@@ -1,3 +1,7 @@
+## 1.2.1
+
+* Fixed a nasty bug where `ActiveModel` forms with form builder support wouldn't deserialize properly. A million Thanks to @karolsarnacki for finding this and providing an exemplary failing test. <3
+
 ## 1.2.0
 
 ### Breakage
@@ -11,16 +15,29 @@
 
     Including this module will add `#column_for_attribute` and other methods need by form builders to automatically guess the type of a property.
 
+* `Form#save` no longer passed `self` to the block. You've been warned long enough. ;)
+
 ### Changes
 
+* Renamed `:as` to `:from` to be in line with Representable/Roar, Disposable and Cells. Thanks to @bethesque for pushing this.
+* `:empty` is now `:virtual` and `:virtual` is `writeable: false`. It was too confusing and sucked. Thanks to @bethesque, again, for her moral assistance.
 * `Form#save` with `Composition` now returns true only if all composite models saved.
 * `Form::copy_validations_from` allows copying custom validators now.
 * New call style for `::properties`. Instead of an array, it's now `properties :title, :genre`.
 * All options are evaluated with `pass_options: true`.
+* All transforming representers are now created and stored on class level, resulting in simpler code and a 85% speed-up.
 
 ### New Stuff!!!
 
-* `:skip_if`, `:skip_if: :all_blank`.
+* In `#validate`, you can ignore properties now using `:skip_if`.
+
+    ```ruby
+    property :hit, skip_if: lambda { |fragment, *| fragment["title"].blank? }
+    ```
+
+    This works for both properties and nested forms. The property will simply be ignored when deserializing, as if it had never been in the incoming hash/document.
+
+    For nested properties you can use `:skip_if: :all_blank` as a macro to ignore a nested form if all values are blank.
 * You can now specify validations right in the `::property` call.
 
     ```ruby
@@ -28,19 +45,48 @@
     ```
 
     Thanks to @zubin for this brillant idea!
-* Wanna parse JSON in `#validate`? Include `Reform::Form::JSON`.
-* Dirty
-* :sync
-* :save
-* `Sync::SkipUnchanged`.
-* Adding `:base` errors now works. Thanks to @bethesque.
+
+* Reform now tracks which attributes have changed after `#validate`. You can check that using `form.changed?(:title)`.
+* When including `Sync::SkipUnchanged`, the form won't try to assign unchanged values anymore in `#sync`. This is extremely helpful when handling file uploads and the like.
+* Both `#sync` and `#save` can be configured dynamically now.
+
+    When syncing, you can run a lambda per property.
+
+    ```ruby
+    property :title, sync: lambda { |value, options| model.set_title(value) }
+    ```
+
+    This won't run Reform's built-in sync for this property.
+
+    You can also provide the sync lambda at run-time.
+
+    ```ruby
+    form.sync(title: lambda { |value, options| form.model.title = "HOT: #{value}" })
+    ```
+
+    This block is run in the caller's context allowing you to access environment variables.
+
+    Note that the dynamic sync happens _before_ save, so the model id may unavailable.
+
+    You can do the same for saving.
+
+    ```ruby
+    form.save(title: lambda { |value, options| form.model.title = "#{form.model.id} --> #{value}" })
+    ```
+    Again, this block is run in the caller's context.
+
+    The two features are an excellent way to handle file uploads without ActiveRecord's horrible callbacks.
+
+* Adding generic `:base` errors now works. Thanks to @bethesque.
 
     ```ruby
     errors.add(:base, "You are too awesome!")
     ```
 
   This will prefix the error with `:base`.
+* Need your form to parse JSON? Include `Reform::Form::JSON`, the `#validate` method now expects a JSON string and will deserialize and populate the form from the JSON document.
 * Added `Form::schema` to generate a pure representer from the form's representer.
+* Added `:readable` and `:writeable` option which allow to skip reading or writing to the model when `false`.
 
 ## 1.1.1
 

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2013 Nick Sutterer
+Copyright (c) 2013 - 2014 Nick Sutterer
 
 MIT License
 

data/README.md

@@ -98,11 +98,11 @@ class SongForm < Reform::Form
 
 Internally, this form will call `song.title` to populate the title field.
 
-If you, for whatever reasons, want to use a different public name, use `:as`.
+If you, for whatever reasons, want to use a different public name, use `:from`.
 
 ```ruby
 class SongForm < Reform::Form
-  property :name, as: :title
+  property :name, from: :title
 ```
 
 This will still call `song.title` but expose the attribute as `name`.
@@ -633,17 +633,17 @@ As with the built-in coercion, this setter is only called in `#validate`.
 Virtual fields come in handy when there's no direct mapping to a model attribute or when you plan on displaying but not processing a value.
 
 
-### Empty Fields
+### Virtual Fields
 
-Often, fields like `password_confirmation` shouldn't be retrieved from the model. Reform comes with the `:empty` option for that.
+Often, fields like `password_confirmation` should neither be read from nor written back to the model. Reform comes with the `:virtual` option to handle that case.
 
 ```ruby
 class PasswordForm < Reform::Form
   property :password
-  property :password_confirmation, :empty => true
+  property :password_confirmation, virtual: true
 ```
 
-Here, the model won't be queried for a `password_confirmation` field when creating and rendering the form. Likewise, when saving the form, the input value is not written to the decorated model. It is only readable in validations and when saving the form.
+Here, the model won't be queried for a `password_confirmation` field when creating and rendering the form. When saving the form, the input value is not written to the decorated model. It is only readable in validations and when saving the form manually.
 
 ```ruby
 form.validate("password" => "123", "password_confirmation" => "321")
@@ -660,11 +660,11 @@ form.save do |nested|
 
 ### Read-Only Fields
 
-Almost identical, the `:virtual` option makes fields read-only. Say you want to show a value, but not process it after submission, this option is your friend.
+When you want to show a value but skip processing it after submission the `:writeable` option is your friend.
 
 ```ruby
 class ProfileForm < Reform::Form
-  property :country, :virtual => true
+  property :country, :writeable => false
 ```
 
 This time reform will query the model for the value by calling `model.country`.
@@ -678,6 +678,14 @@ form.save do |nested|
   nested[:country] #=> "Australia"
 ```
 
+### Write-Only Fields
+
+A third alternative is to hide a field's value but write it to the database when syncing. This can be achieved using the `:readable` option.
+
+```ruby
+property :credit_card_number, :readable => false
+```
+
 ## Validations From Models
 
 Sometimes when you still keep validations in your models (which you shouldn't) copying them to a form might not feel right. In that case, you can let Reform automatically copy them.
@@ -869,6 +877,38 @@ form.validate("title" => "Just Kiddin'")
 form.changed?(:title) #=> true
 ```
 
+When including `Sync::SkipUnchanged`, the form won't assign unchanged values anymore in `#sync`.
+
+
+## Dynamically Syncing And Saving Properties
+
+Both `#sync` and `#save` can be configured to run a dynamical lambda per property.
+
+The `sync:` option allows to statically add a lambda to a property.
+
+```ruby
+property :title, sync: lambda { |value, options| model.set_title(value) }
+```
+
+Instead of running Reform's built-in sync for this property the block is run.
+
+You can also provide the sync lambda at run-time.
+
+```ruby
+form.sync(title: lambda { |value, options| form.model.title = "HOT: #{value}" })
+```
+
+This block is run in the caller's context allowing you to access environment variables. Note that the dynamic sync happens _before_ save, so the model id may unavailable.
+
+You can do the same for saving.
+
+```ruby
+form.save(title: lambda { |value, options| form.model.title = "#{form.model.id} --> #{value}" })
+```
+Again, this block is run in the caller's context.
+
+The two features are an excellent way to handle file uploads without ActiveRecord's horrible callbacks.
+
 
 ## Undocumented Features
 

data/lib/reform/contract.rb

@@ -29,12 +29,27 @@ module Reform
 
     module PropertyMethods
       def property(name, options={}, &block)
-        options[:private_name] = options.delete(:as)
+        deprecate_as!(options)
+        options[:private_name] = options.delete(:from)
         options[:coercion_type] = options.delete(:type)
         options[:features] ||= []
         options[:features] += features.keys if block_given?
         options[:pass_options] = true
-        options[:virtual] = true if options[:empty] # TODO: check TODO and fix naming!
+
+        # readable and writeable is true as it's not == false
+
+        if reform_2_0
+          if options.delete(:virtual)
+            options[:_readable]  = false
+            options[:_writeable] = false
+          else
+            options[:_readable]  = options.delete(:readable)
+            options[:_writeable] = options.delete(:writeable)
+          end
+
+        else # TODO: remove me in 2.0.
+          deprecate_virtual_and_empty!(options)
+        end
 
         validates(name, options.delete(:validates).dup) if options[:validates]
 
@@ -98,10 +113,24 @@ module Reform
 
     require 'reform/contract/setup'
     include Setup
+
+    def self.representers # keeps all transformation representers for one class.
+      @representers ||= {}
+    end
+
+    def self.representer(name=nil, options={}, &block)
+      return representer_class.each(&block) if name == nil
+      return representers[name] if representers[name] # don't run block as this representer is already setup for this form class.
+
+      only_forms = options[:all] ? false : true
+      base       = options[:superclass] || representer_class
+
+      representers[name] = Class.new(base).each(only_forms, &block) # let user modify representer.
+    end
+
     require 'reform/contract/validate'
     include Validate
 
-
     def errors # FIXME: this is needed for Rails 3.0 compatibility.
       @errors ||= Errors.new(self)
     end
@@ -111,10 +140,35 @@ module Reform
     attr_accessor :fields
     attr_writer :errors # only used in top form. (is that true?)
 
-    def mapper
+    def mapper # FIXME: do we need this with class-level representers?
       self.class.representer_class
     end
 
+    def self.deprecate_as!(options) # TODO: remove me in 2.0.
+      return unless as = options.delete(:as)
+      options[:from] = as
+      warn "[Reform] The :as options got renamed to :from. See https://github.com/apotonick/reform/wiki/Migration-Guide and have a nice day."
+    end
+
+    def self.deprecate_virtual_and_empty!(options) # TODO: remove me in 2.0.
+      if options.delete(:virtual)
+        warn "[Reform] The :virtual option has changed! Check https://github.com/apotonick/reform/wiki/Migration-Guide and have a good day."
+        options[:_readable] = true
+        options[:_writeable] = false
+      end
+
+      if options[:empty]
+        warn "[Reform] The :empty option has changed! Check https://github.com/apotonick/reform/wiki/Migration-Guide and have a good day."
+        options[:_readable]  = false
+        options[:_writeable] = false
+      end
+    end
+
+    inheritable_attr :reform_2_0 # TODO: remove me in 2.0.
+    def self.reform_2_0!
+      self.reform_2_0= true
+    end
+
     def self.register_feature(mod)
       features[mod] = true
     end

data/lib/reform/contract/setup.rb

@@ -6,14 +6,25 @@ module Reform
         @fields = setup_fields  # delegate all methods to Fields instance.
       end
 
+      # Setup#to_hash will create a nested hash of property values from the model.
+      # Nested properties will be recursively wrapped in a form instance.
+      def setup_representer
+        self.class.representer(:setup) do |dfn| # only nested forms.
+          dfn.merge!(
+            :representable => false, # don't call #to_hash, only prepare.
+            :prepare       => lambda { |model, args| args.binding[:form].new(model) } # wrap nested properties in form.
+          )
+        end
+      end
+
       def setup_fields
-        representer = mapper.new(aliased_model).extend(Setup::Representer)
+        representer = setup_representer.new(aliased_model)
         options     = setup_options(Reform::Representer::Options[]) # handles :empty.
 
+        # populate the internal @fields set with data from the model.
         create_fields(mapper.fields, representer.to_hash(options))
       end
 
-      # DISCUSS: setting up the Validation (populating with values) will soon be handled with Disposable::Twin logic.
       def create_fields(field_names, fields)
         Fields.new(field_names, fields)
       end
@@ -26,31 +37,14 @@ module Reform
       include SetupOptions
 
 
-      # Mechanics for setting up initial Field values.
-      module Representer
-        def to_hash(*)
-          nested_forms do |attr|
-            attr.merge!(
-              :representable => false, # don't call #to_hash.
-              :prepare       => lambda do |model, args|
-                args.binding[:form].new(model)
-              end
-            )
-          end
-
-          super
-        end
-      end # Representer
-
-
-      module Empty
+      module Readable
         def setup_options(options)
-          empty_fields = mapper.representable_attrs.find_all { |d| d[:empty] }.collect  { |d| d.name.to_sym }
+          empty_fields = mapper.representable_attrs.find_all { |d| d[:_readable] == false }.collect  { |d| d.name.to_sym }
 
           options.exclude!(empty_fields)
         end
       end
-      include Empty
+      include Readable
     end
   end # Setup
 end

data/lib/reform/contract/validate.rb

@@ -1,24 +1,4 @@
 module Reform::Contract::Validate
-  module NestedValid
-    def to_hash(*)
-      nested_forms do |attr|
-        attr.merge!(
-          :serialize => lambda { |object, args|
-
-            # FIXME: merge with Validate::Writer
-            options = args.user_options.dup
-            options[:prefix] = options[:prefix].dup # TODO: implement Options#dup.
-            options[:prefix] << args.binding.name # FIXME: should be #as.
-
-            object.validate!(options) # recursively call valid?
-          },
-        )
-      end
-
-      super
-    end
-  end
-
   def validate
     options = {:errors => errs = Reform::Contract::Errors.new(self), :prefix => []}
 
@@ -28,15 +8,32 @@ module Reform::Contract::Validate
 
     errors.valid?
   end
+
   def validate!(options)
     prefix = options[:prefix]
 
     # call valid? recursively and collect nested errors.
-    mapper.new(fields).extend(NestedValid).to_hash(options) # TODO: only include nested forms here.
+    valid_representer.new(fields).to_hash(options) # TODO: only include nested forms here.
 
     valid?  # this validates on <Fields> using AM::Validations, currently.
 
     options[:errors].merge!(self.errors, prefix)
   end
 
+private
+
+  # runs form.validate! on all nested forms
+  def valid_representer
+    self.class.representer(:valid) do |dfn|
+      dfn.merge!(
+        :serialize => lambda { |form, args|
+          options = args.user_options.dup
+          options[:prefix] = options[:prefix].dup # TODO: implement Options#dup.
+          options[:prefix] << args.binding.name # FIXME: should be #as.
+
+          form.validate!(options) # recursively call valid? on nested form.
+        }
+      )
+    end
+  end
 end

data/lib/reform/form/active_model.rb

@@ -29,22 +29,20 @@ module Reform::Form::ActiveModel
       return super unless params.is_a?(Hash)
       # TODO: run this only for hash deserialization, but generically (#deserialize_hash ?).
 
-      mapper.new(self).nested_forms do |attr, model| # FIXME: make this simpler.
-        rename_nested_param_for!(params, attr)
-      end
+      self.class.representer { |dfn| rename_nested_param_for!(params, dfn) }
 
       super
     end
 
   private
-    def rename_nested_param_for!(params, attr)
-      nested_name = "#{attr.name}_attributes"
+    def rename_nested_param_for!(params, dfn)
+      nested_name = "#{dfn.name}_attributes"
       return unless params.has_key?(nested_name)
 
-      value = params["#{attr.name}_attributes"]
-      value = value.values if attr[:collection]
+      value = params["#{dfn.name}_attributes"]
+      value = value.values if dfn[:collection]
 
-      params[attr.name] = value
+      params[dfn.name] = value
     end
   end # FormBuilderMethods