reform 1.0.4 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: be845dd1b0e8a941df46ef6ed8d582b440b44acf
-  data.tar.gz: 4a4d7e81be355c4164fb884060eb07194bad0af6
+  metadata.gz: b95fac93b5186e174e6e2aef263bff4bf5305210
+  data.tar.gz: bafdc2c15f78fa1fe27e9b554c32d3aafcfb4fbd
 SHA512:
-  metadata.gz: 0c3c10fbedfb3cf9df5afdfbd98088a1ef948b9aa7b8730d294673b624309786658a450dcdafdd4571ef35ffbbfd3e3e724accd1bc2e250f9345c323f57640c6
-  data.tar.gz: 3c24007806a3469ce08ecc1ff13c40bf7e271b46d8fdaa8e098e2da0ed1a62571c51fcd7e0feca928c56c01c49bda1d632cb47c8aa7f2fdf9c9255274fbb2c5d
+  metadata.gz: a55abac9d331f20d75fa66ed8950c35e5cd16460fc054a182c6d0cfb0c4d9e1524349553b9aeeeafa33b75453d35ce3c8476ad8f0adce7775c41d99d4176338a
+  data.tar.gz: 61d436b3f4cb696e2cffa02f7e3ff1179741209da8a4f2073e36da45d12971983ff19be9ffdcb0b515ed601f933240685287fa208287a63f521d3d4dbcb2e99c

data/CHANGES.md

@@ -1,3 +1,16 @@
+## 1.1.0
+
+* Deprecate first block argument in save. It's new signature is `save { |hash| }`. You already got the form instance when calling `form.save` so there's no need to pass it into the block.
+* `#validate` does **not** touch any model anymore. Both single values and collections are written to the model after `#sync` or `#save`.
+* Coercion now happens in `#validate`, only.
+* You can now define forms in modules including `Reform::Form::Module` to improve reusability.
+* Inheriting from forms and then overriding/extending properties with `:inherit` now works properly.
+* You can now define methods in inline forms.
+* Forms can now also deserialize other formats, e.g. JSON. This allows them to be used as a contract for API endpoints and in Operations in Trailblazer.
+* Composition forms no longer expose readers to the composition members. The composition is available via `Form#model`, members via `Form#model[:member_name]`.
+* ActiveRecord support is now included correctly and passed on to nested forms.
+* Undocumented/Experimental: Scalar forms. This is still WIP.
+
 ## 1.0.4
 
 Reverting what I did in 1.0.3. Leave your code as it is. You may override a writers like `#title=` to sanitize or filter incoming data, as in

data/Gemfile

@@ -3,4 +3,4 @@ source 'https://rubygems.org'
 gemspec
 
 # gem 'representable', path: "../representable"
-# gem "disposable", path: "../disposable"
+# gem "disposable", path: "../disposable"

data/README.md

@@ -147,24 +147,29 @@ Sometimes, you need to do stuff manually.
 
 ## Saving Forms Manually
 
-This is where you call `#save` with a block. This won't touch the models at all but give you a nice hash, so you can do it yourself.
+Calling `#save` with a block doesn't do anything but providing you a nested hash with all the validated input. This allows you to implement the saving yourself.
 
-Note that you can call `#sync` and _then_ call `#save` with the block to save models yourself.
+The block parameter is a nested hash of the form input.
 
 ```ruby
-  if @form.validate(params[:song])
+  @form.save do |hash|
+    hash      #=> {title: "Rio", length: "366"}
 
-    @form.save do |data, nested|
-      data.title  #=> "Rio"
-      data.length #=> "366"
+    Song.create(hash)
+  end
+```
 
-      nested      #=> {title: "Rio", length: "366"}
+You can always access the form's model. This is helpful when you were using populators to set up objects when validating.
 
-      Song.create(nested)
-    end
+```ruby
+  @form.save do |nested|
+    album = @form.album.model
+
+    album.update_attributes(nested[:album])
+  end
 ```
 
-While `data` gives you an object exposing the form property readers, `nested` is a hash reflecting the nesting structure of your form. Note how you can use arbitrary code to create/update models - in this example, we used `Song::create`.
+Note that you can call `#sync` and _then_ call `#save { |hsh| }` to save models yourself.
 
 
 ## Contracts
@@ -200,12 +205,14 @@ In future versions and with the upcoming [Trailblazer framework](https://github.
 Applying a contract is simple, all you need is a populated object (e.g. an album after `#update_attributes`).
 
 ```ruby
-album.update_attributes(..)
+album.assign_attributes(..)
 
-if AlbumContract.new(album).validate
+contract = AlbumContract.new(album)
+
+if contract.validate
   album.save
 else
-  raise album.errors.messages.inspect
+  raise contract.errors.messages.inspect
 end
 ```
 
@@ -486,6 +493,47 @@ Here's how the block parameters look like.
 end
 ```
 
+## Inheritance
+
+Forms can be derived from other forms and will inherit all properties and validations.
+
+```ruby
+class AlbumForm < Reform::Form
+  property :title
+
+  collection :songs do
+    property :title
+
+    validates :title, presence: true
+  end
+end
+```
+
+Now, a simple inheritance can add fields.
+
+```ruby
+class CompilationForm < AlbumForm
+  property :composers do
+    property :name
+  end
+end
+```
+
+This will _add_ `composers` to the existing fields.
+
+You can also partially override fields using `:inherit`.
+
+```ruby
+class CompilationForm < AlbumForm
+  property :songs, inherit: true do
+    property :band_id
+    validates :band_id, presence: true
+  end
+end
+```
+
+Using `inherit:` here will extend the existing `songs` form with the `band_id` field. Note that this simply uses [representable's inheritance mechanism](https://github.com/apotonick/representable/#partly-overriding-properties).
+
 ## Coercion
 
 Often you want incoming form data to be converted to a type, like timestamps. Reform uses [virtus](https://github.com/solnic/virtus) for coercion, the DSL is seamlessly integrated into Reform with the `:type` option.

data/lib/reform/composition.rb

@@ -1,5 +1,6 @@
 require 'disposable/composition'
 
+# TODO: replace that with lazy Twin and Composition from Disposable.
 module Reform
   class Expose
     include Disposable::Composition

data/lib/reform/contract.rb

@@ -1,31 +1,40 @@
 require 'forwardable'
 require 'uber/inheritable_attr'
+require 'uber/delegates'
 
 require 'reform/representer'
 
 module Reform
   # Gives you a DSL for defining the object structure and its validations.
   class Contract # DISCUSS: make class?
-    extend Forwardable
+    extend Uber::Delegates
 
     extend Uber::InheritableAttr
+    # representer_class gets inherited (cloned) to subclasses.
     inheritable_attr :representer_class
-    self.representer_class = Reform::Representer.for(:form_class => self)
+    self.representer_class = Reform::Representer.for(:form_class => self) # only happens in Contract/Form.
+    # this should be the only mechanism to inherit, features should be stored in this as well.
 
+
+    # each contract keeps track of its features and passes them onto its local representer_class.
+    # gets inherited, features get automatically included into inline representer.
+    # TODO: the representer class should handle that, e.g. in options (deep-clone when inheriting.)
     inheritable_attr :features
-    self.features = []
+    self.features = {}
+
 
     RESERVED_METHODS = [:model, :aliased_model, :fields, :mapper] # TODO: refactor that so we don't need that.
 
 
     module PropertyMethods
-      extend Forwardable
-
       def property(name, options={}, &block)
         options[:private_name] = options.delete(:as)
 
-        # at this point, :extend is a Form class.
-        options[:features] = features if block_given?
+        options[:coercion_type] = options.delete(:type)
+
+        options[:features] ||= []
+        options[:features] += features.keys if block_given?
+
         definition = representer_class.property(name, options, &block)
         setup_form_definition(definition) if block_given? or options[:form]
 
@@ -45,7 +54,8 @@ module Reform
 
       def setup_form_definition(definition)
         options = {
-          :form         => definition[:form] || definition[:extend].evaluate(nil), # :form is always just a Form class name.
+          # TODO: make this a bit nicer. why do we need :form at all?
+          :form         => (definition[:extend] and definition[:extend].evaluate(nil)) || definition[:form], # :form is always just a Form class name.
           :pass_options => true, # new style of passing args
           :prepare      => lambda { |form, args| form }, # always just return the form without decorating.
           :representable => true, # form: Class must be treated as a typed property.
@@ -58,13 +68,7 @@ module Reform
       def create_accessor(name)
         handle_reserved_names(name)
 
-        # Make a module that contains these very accessors, then include it
-        # so they can be overridden but still are callable with super.
-        accessors = Module.new do
-          extend Forwardable # DISCUSS: do we really need Forwardable here?
-          delegate [name, "#{name}="] => :fields
-        end
-        include accessors
+        delegates :fields, name, "#{name}=" # Uber::Delegates
       end
 
       def handle_reserved_names(name)
@@ -79,6 +83,7 @@ module Reform
     include ActiveModel::Validations
 
 
+
     attr_accessor :model
 
     require 'reform/contract/setup'
@@ -100,6 +105,10 @@ module Reform
       self.class.representer_class
     end
 
+    def self.register_feature(mod)
+      features[mod] = true
+    end
+
     alias_method :aliased_model, :model
 
 

data/lib/reform/form.rb

@@ -2,6 +2,7 @@ require 'ostruct'
 
 require 'reform/contract'
 require 'reform/composition'
+require 'reform/form/module'
 
 module Reform
   class Form < Contract
@@ -24,5 +25,9 @@ module Reform
       # TODO: cache the Expose.from class!
       Reform::Expose.from(mapper).new(:model => model)
     end
+
+
+    require 'reform/form/scalar'
+    extend Scalar::Property # experimental feature!
   end
 end

data/lib/reform/form/active_model.rb

@@ -1,9 +1,11 @@
+require 'reform/form/active_model/model_validations'
+
 module Reform::Form::ActiveModel
   module FormBuilderMethods # TODO: rename to FormBuilderCompat.
     def self.included(base)
       base.class_eval do
         extend ClassMethods # ::model_name
-        features << FormBuilderMethods
+        register_feature FormBuilderMethods
       end
     end
 
@@ -48,9 +50,9 @@ module Reform::Form::ActiveModel
   def self.included(base)
     base.class_eval do
       extend ClassMethods
-      features << ActiveModel
+      register_feature ActiveModel
 
-      delegate [:persisted?, :to_key, :to_param, :id] => :model
+      delegates :model, *[:persisted?, :to_key, :to_param, :id] # Uber::Delegates
 
       def to_model # this is called somewhere in FormBuilder and ActionController.
         self

data/lib/reform/form/active_model/model_validations.rb

@@ -0,0 +1,98 @@
+module Reform::Form::ActiveModel
+  module ModelValidations
+    # TODO: extract Composition behaviour.
+    # reduce code in Mapping.
+
+    class ValidationCopier
+
+      def self.copy(form_class, mapping, models)
+        if models.is_a?(Hash)
+          models.each do |model_name, model|
+            new(form_class, mapping, model, model_name).copy
+          end
+        else
+          new(form_class, mapping, models).copy
+        end
+      end
+
+      def initialize(form_class, mapping, model, model_name=nil)
+        @form_class = form_class
+        @mapping = mapping
+        @model = model
+        @model_name = model_name
+      end
+
+      def copy
+        @model.validators.each(&method(:add_validator))
+      end
+
+    private
+
+      def add_validator(validator)
+        attributes = inverse_map_attributes(validator.attributes)
+        if attributes.any?
+          @form_class.validates(*attributes, {validator.kind => validator.options})
+        end
+      end
+
+      def inverse_map_attributes(attributes)
+        @mapping.inverse_image(create_attributes(attributes))
+      end
+
+      def create_attributes(attributes)
+        attributes.map do |attribute|
+          [@model_name, attribute].compact
+        end
+      end
+
+    end
+
+    class Mapping
+      def self.from_representable_attrs(attrs)
+        new.tap do |mapping|
+          attrs.each do |dfn|
+            from = dfn.name.to_sym
+            to = [dfn[:on], (dfn[:private_name] || dfn.name)].compact.map(&:to_sym)
+            mapping.add(from, to)
+          end
+        end
+      end
+
+      def initialize
+        @forward_map = {}
+        @inverse_map = {}
+      end
+
+      # from is a symbol attribute
+      # to is an 1 or 2 element array, depending on whether the attribute is 'namespaced', as it is with composite forms.
+      # eg, add(:phone_number, [:person, :phone])
+      def add(from, to)
+        raise 'Mapping is not one-to-one' if @forward_map.has_key?(from) || @inverse_map.has_key?(to)
+        @forward_map[from] = to
+        @inverse_map[to] = from
+      end
+
+      def forward_image(attrs)
+        @forward_map.values_at(*attrs).compact
+      end
+
+      def forward(attr)
+        @forward_map[attr]
+      end
+
+      def inverse_image(attrs)
+        @inverse_map.values_at(*attrs).compact
+      end
+
+      def inverse(attr)
+        @inverse_map[attr]
+      end
+
+    end
+
+    def copy_validations_from(models)
+      ValidationCopier.copy(self, Mapping.from_representable_attrs(representer_class.representable_attrs), models)
+    end
+
+  end
+end

data/lib/reform/form/active_record.rb

@@ -1,6 +1,7 @@
 module Reform::Form::ActiveRecord
   def self.included(base)
     base.class_eval do
+      register_feature Reform::Form::ActiveRecord
       include Reform::Form::ActiveModel
       extend ClassMethods
     end
@@ -37,7 +38,13 @@ module Reform::Form::ActiveRecord
   def model_for_property(name)
     return model unless is_a?(Reform::Form::Composition) # i am too lazy for proper inheritance. there should be a ActiveRecord::Composition that handles this.
 
-    model_name = mapper.representable_attrs[name][:on]
+    model_name = mapper.representable_attrs.get(name)[:on]
     model[model_name]
   end
+
+  # Delegate column for attribute to the model to support simple_form's
+  # attribute type interrogation.
+  def column_for_attribute(name)
+    model_for_property(name).column_for_attribute(name)
+  end
 end

data/lib/reform/form/coercion.rb

@@ -1,15 +1,15 @@
-require 'representable/decorator/coercion'
+require 'representable/coercion'
 
 module Reform::Form::Coercion
   def self.included(base)
     base.extend(ClassMethods)
-    base.features << self
+    base.send(:register_feature, self)
   end
 
   module ClassMethods
-    def representer_class
+    def representer_class # TODO: check out how we can utilise Config#features.
       super.class_eval do
-        include Representable::Decorator::Coercion unless self < Representable::Decorator::Coercion # DISCUSS: include it once. why do we have to check this?
+        include Representable::Coercion
         self
       end
     end

data/lib/reform/form/composition.rb

@@ -16,12 +16,6 @@ module Reform::Form::Composition
       @model_class ||= Reform::Composition.from(representer_class)
     end
 
-    def property(name, options={})
-      super.tap do |definition|
-        handle_deprecated_model_accessor(options[:on]) unless options[:skip_accessors] # TODO: remove in 1.2.
-      end
-    end
-
     # Same as ActiveModel::model but allows you to define the main model in the composition
     # using +:on+.
     #
@@ -32,8 +26,6 @@ module Reform::Form::Composition
 
       composition_model = options[:on] || main_model
 
-      handle_deprecated_model_accessor(composition_model)  unless options[:skip_accessors] # TODO: remove in 1.2.
-
       # FIXME: this should just delegate to :model as in FB, and the comp would take care of it internally.
       [:persisted?, :to_key, :to_param].each do |method|
         define_method method do
@@ -41,16 +33,7 @@ module Reform::Form::Composition
         end
       end
 
-      alias_method main_model, composition_model # #hit => model.song. # TODO: remove in 1.2.
-    end
-
-  private
-    def handle_deprecated_model_accessor(name, aliased=name)
-      define_method name do # form.band -> composition.band
-        warn %{[Reform] Deprecation WARNING: When using Composition, you may not call Form##{name} anymore to access the contained model. Please use Form#model[:#{name}] and have a lovely day!}
-
-        @model[name]
-      end
+      self
     end
   end
 
@@ -64,7 +47,7 @@ module Reform::Form::Composition
   end
 
   def to_hash(*args)
-    mapper.new(fields).to_hash(*args)
+    mapper.new(fields).to_hash(*args) # do not map names, yet. this happens in #to_nested_hash
   end
 
 private