reform 0.2.7 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e447e702b5effb25c8b881fb6c3056e57d39b5f9
-  data.tar.gz: 83ab3bdb3a48858fa273ea8985eb04bdee24e5d5
+  metadata.gz: 331784eaf17a8dc17f08c7c39cdb60af3bf502ed
+  data.tar.gz: 48cc28e685c889c3fd7ca7290215c5c4d1801ec1
 SHA512:
-  metadata.gz: 6891ad8debef392f1ac60f79c962bb42004325b15aa0d5ef460c1456ec03152c12dacf0e933193f2b0630042af1bc4a86ea9f564ab69e2f2d369cc3517a9dea0
-  data.tar.gz: 4a4014071fb1f71da66d6124ba79f007d1e09bd2854ba6f989e299e931c158a5500408c171eb7f714704b930246d3ff5df46cd00a9d87d00ec49ef501d4201c9
+  metadata.gz: 983557534185ed0d80afaccd6b433abb2ffe97fb5e44898bb915bb8d44b92f68d11447e2e30d7839be23c8f91cd374ffefe98a704eabe8f54763f13a09ade2dd
+  data.tar.gz: fbf1dc09a1197491e17fd4e36d137a98309fa05310f18e40804093ba6e1af3b08959f524293eef751fe5cbc0a21e73bd915d1a76fdddf4eb63091e203332342e

data/CHANGES.md

@@ -1,3 +1,21 @@
+## 1.0.0
+
+* Removed `Form::DSL` in favour of `Form::Composition`.
+* Simplified nested forms. You can now do
+    ```ruby
+    validates :songs, :length => {:minimum => 1}
+    validates :hit, :presence => true
+    ```
+* Allow passing symbol hash keys into `#validate`.
+* Unlimited nesting of forms, if you really want that.
+* `save` gets called on all nested forms automatically, disable with `save: false`.
+* Renaming with `as:` now works everywhere.
+* Fixes to make `Composition` work everywhere.
+* Extract setup and validate into `Contract`.
+* Automatic population with `:populate_if_empty` in `#validate`.
+* Remove `#from_hash` and `#to_hash`.
+* Introduce `#sync` and make `#save` less smart.
+
 ## 0.2.7
 
 * Last release supporting Representable 1.7.

data/Gemfile

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

data/README.md

@@ -4,11 +4,6 @@ Decouple your models from forms. Reform gives you a form object with validations
 
 Although reform can be used in any Ruby framework, it comes with [Rails support](#rails-integration), works with [simple_form and other form gems](#formbuilder-support), allows nesting forms to implement [has_one](#nesting-forms-1-1-relations) and [has_many](#nesting-forms-1-n-relations) relationships, can [compose a form](#compositions) from multiple objects and gives you [coercion](#coercion).
 
-# Development Status
-
-Dear Reform users - you know I love all of you. Reform is currently being improved by myself. I am definitely *not* resisting all of the feature requests (especially about nesting, model validations, automatic model setup when validating has_many, etc.) but working hard to make it better. Expect a new Reform version _and_ better README mid-late April and please refrain from telling me how lazy I am. Thanks and see you soon!!! :heart:
-
-
 ## Installation
 
 Add this line to your Gemfile:
@@ -17,6 +12,14 @@ Add this line to your Gemfile:
 gem 'reform'
 ```
 
+## Nomenclatura
+
+Reform comes with two base classes.
+
+* `Form` is what made you come here - it gives you a form class to handle all validations, wrap models, allow rendering with Rails form helpers, simplifies saving of models, and more.
+* `Contract` gives you a sub-set of `Form`: [this class](#contracts) is meant for API validation where already populated models get validated without having to maintain validations in the model classes.
+
+
 ## Defining Forms
 
 You're working at a famous record label and your job is archiving all the songs, albums and artists. You start with a form to populate your `songs` table.
@@ -34,7 +37,20 @@ end
 To add fields to the form use the `::property` method. Also, validations no longer go into the model but sit in the form.
 
 
-## Using Forms
+## The API
+
+Forms have a ridiculously simple API with only a handful of public methods.
+
+1. `#initialize` always requires a model that the form represents.
+2. `#validate(params)` will run all validations for the form with the input data. Its return value is the boolean result of the validations.
+3. `#errors` returns validation messages in a classy ActiveModel style.
+4. `#sync` writes form data back to the model. This will only use setter methods on the model(s).
+5. `#save` (optional) will call `#save` on the model and nested models. Note that this implies a `#sync` call.
+
+In addition to the main API, forms expose accessors to the defined properties. This is used for rendering or manual operations.
+
+
+## Setup
 
 In your controller you'd create a form instance and pass in the models you wanna work on.
 
@@ -54,6 +70,25 @@ class SongsController
   end
 ```
 
+Reform will read property values from the model in setup. Given the following form class.
+
+```ruby
+class SongForm < Reform::Form
+  property :title
+```
+
+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`.
+
+```ruby
+class SongForm < Reform::Form
+  property :name, as: :title
+```
+
+This will still call `song.title` but expose the attribute as `name`.
+
+
 ## Rendering Forms
 
 Your `@form` is now ready to be rendered, either do it yourself or use something like Rails' `#form_for`, `simple_form` or `formtastic`.
@@ -65,7 +100,10 @@ Your `@form` is now ready to be rendered, either do it yourself or use something
   = f.input :title
 ```
 
-## Validating Forms
+Nested forms and collections can easily rendered with `fields_for`, etc. Just use Reform as if it would be an ActiveModel instance in the view layer.
+
+
+## Validation
 
 After a form submission, you wanna validate the input.
 
@@ -86,9 +124,32 @@ Note that Reform only updates values of the internal form attributes - the under
 This allows rendering the form after `validate` with the data that has been submitted. However, don't get confused, the model's values are still the old, original values and are only changed after a `#save` or `#sync` operation.
 
 
+## Syncing Back
+
+After validation, you have two choices: either call `#save` and let Reform sort out the rest. Or call `#sync`, which will write all the properties back to the model. In a nested form, this works recursively, of course.
+
+It's then up to you what to do with the updated models - they're still unsaved.
+
+
 ## Saving Forms
 
-We provide a bullet-proof way to save your form data: by letting _you_ do it!
+The easiest way to save the data is to call `#save` on the form.
+
+```ruby
+    @form.save  #=> populates song with incoming data
+                #   by calling @form.song.title= and @form.song.length=.
+```
+
+This will sync the data to the model and then call `song.save`.
+
+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.
+
+Note that you can call `#sync` and _then_ call `#save` with the block to save models yourself.
 
 ```ruby
   if @form.validate(params[:song])
@@ -97,7 +158,7 @@ We provide a bullet-proof way to save your form data: by letting _you_ do it!
       data.title  #=> "Rio"
       data.length #=> "366"
 
-      nested      #=> {title: "Rio"}
+      nested      #=> {title: "Rio", length: "366"}
 
       Song.create(nested)
     end
@@ -105,17 +166,50 @@ We provide a bullet-proof way to save your form data: by letting _you_ do it!
 
 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`.
 
-To push the incoming data to the models directly, call `#save` without the block.
+
+## Contracts
+
+Contracts give you a sub-set of the `Form` API.
+
+1. `#initialize` accepts an already populated model.
+2. `#validate` will run defined validations (without accepting a params hash as in `Form`).
+
+Contracts can be used to completely remove validation logic from your model classes. Validation should happen in a separate layer - a `Contract`.
+
+### Defining Contracts
+
+A contract looks like a form.
 
 ```ruby
-    @form.save  #=> populates song with incoming data
-                #   by calling @form.song.title= and @form.song.length=.
+class AlbumContract < Reform::Contract
+  property :title
+  validates :title, length: {minimum: 9}
+
+  collection :songs do
+    property :title
+    validates :title, presence: true
+  end
 ```
 
-Think of `@form.save` as a sync operation where the submitted data is written to your models using public setters.
+It defines the validations and the object graph to be run.
+
+In future versions and with the upcoming [Trailblazer framework](https://github.com/apotonick/trailblazer), contracts can be inherited from forms, representers, and cells, and vice-versa. Actually this already works with representer inheritance - let me know if you need help.
 
-Note that this does _not_ call `save` on your models per default: this only happens in an ActiveRecord environment or when `Form::ActiveRecord` is mixed in (learn more [here](https://github.com/apotonick/reform#activerecord-compatibility)).
+### Using Contracts
 
+Applying a contract is simple, all you need is a populated object (e.g. an album after `#update_attributes`).
+
+```ruby
+album.update_attributes(..)
+
+if AlbumContract.new(album).validate
+  album.save
+else
+  raise album.errors.messages.inspect
+end
+```
+
+Contracts help you to make your data layer a dumb persistance tier. My [upcoming book discusses that in detail](http://nicksda.apotomo.de).
 
 
 ## Nesting Forms: 1-1 Relations
@@ -201,6 +295,7 @@ Supposed you use reform's automatic save without a block, the following assignme
 ```ruby
 form.song.title       = "Hungry Like The Wolf"
 form.song.artist.name = "Duran Duran"
+form.song.save
 ```
 
 ## Nesting Forms: 1-n Relations
@@ -266,6 +361,69 @@ end
 ```
 
 
+## Nesting Configuration
+
+### Turning Off Autosave
+
+You can assign Reform to _not_ call `save` on a particular nested model (per default, it is called automatically on all nested models).
+
+```ruby
+class AlbumForm < Reform::Form
+  # ...
+
+  collection :songs, save: false do
+    # ..
+  end
+```
+
+The `:save` options set to false won't save models.
+
+
+### Populating Forms For Validation
+
+With a complex nested setup it can sometimes be painful to setup the model object graph.
+
+Let's assume you rendered the following form.
+
+```ruby
+@form = AlbumForm.new(Album.new(songs: [Song.new, Song.new]))
+```
+
+This will render two nested forms to create new songs.
+
+When **validating**, you're supposed to setup the very same object graph, again. Reform has no way of remembering what the object setup was like a request ago.
+
+So, the following code will fail.
+
+```ruby
+@form = AlbumForm.new(Album.new).validate(params[:album])
+```
+
+However, you can advise Reform to setup the correct objects for you.
+
+```ruby
+class AlbumForm < Reform::Form
+  # ...
+
+  collection :songs, populate_if_empty: Song do
+    # ..
+  end
+```
+
+This works for both `property` and `collection` and instantiates `Song` objects where they're missing when calling `#validate`.
+
+If you wanna create the objects yourself, because you're smarter than Reform, do it with a lambda.
+
+```ruby
+class AlbumForm < Reform::Form
+  # ...
+
+  collection :songs, populate_if_empty: lambda { |fragment, args| Song.new } do
+    # ..
+  end
+```
+
+
 ## Compositions
 
 Sometimes you might want to embrace two (or more) unrelated objects with a single form. While you could write a simple delegating composition yourself, reform comes with it built-in.
@@ -405,7 +563,9 @@ Reform doesn't really know whether it's working with a PORO, an `ActiveRecord` i
 
 When rendering the form, reform calls readers on the decorated model to retrieve the field data (`Song#title`, `Song#length`).
 
-When saving a submitted form, the same happens using writers. Reform simply calls `Song#title=(value)`. No knowledge is required about the underlying database layer.
+When syncing a submitted form, the same happens using writers. Reform simply calls `Song#title=(value)`. No knowledge is required about the underlying database layer.
+
+The same applies to saving: Reform will call `#save` on the main model and nested models.
 
 Nesting forms only requires readers for the nested properties as `Album#songs`.
 
@@ -426,7 +586,6 @@ However, you should know about two things.
 Reform provides the following `ActiveRecord` specific features. They're mixed in automatically in a Rails/AR setup.
 
  * Uniqueness validations. Use `validates_uniqueness_of` in your form.
- * Calling `Form#save` will explicitely call `save` on your model (added in 0.2.1) which will usually trigger a database insertion or update.
 
 As mentioned in the [Rails Integration](https://github.com/apotonick/reform#rails-integration) section some Rails 4 setups do not properly load.
 
@@ -518,6 +677,26 @@ class SongForm < Reform::Form
 
 This will capitalize the title _after_ calling `form.validate` but _before_ validation happens. Note that you can use `super` to call the original setter.
 
+
+## Undocumented Features
+
+_(Please don't read this section!)_
+
+
+### Populator
+
+You can run your very own populator logic if you're keen (and you know what you're doing).
+
+```ruby
+class AlbumForm < Reform::Form
+  # ...
+
+  collection :songs, populator: lambda { |fragment, args| args.binding[:form].new(Song.find fragment[:id]) } do
+    # ..
+  end
+```
+
+
 ## Support
 
 If you run into any trouble chat with us on irc.freenode.org#trailblazer.
@@ -532,4 +711,4 @@ If you run into any trouble chat with us on irc.freenode.org#trailblazer.
 
 ### Attributions!!!
 
-Great thanks to [Blake Education](https://github.com/blake-education) for giving us the freedom and time to develop this project while working on their project.
+Great thanks to [Blake Education](https://github.com/blake-education) for giving us the freedom and time to develop this project in 2013 while working on their project.

data/TODO.md

@@ -4,11 +4,22 @@
 * document Form#to_hash and Form#to_nested_hash (e.g. with OpenStruct composition to make it a very simple form)
 * document getter: and representer_exec:
 
-* allow :as to rename nested forms
-* make #nested_forms easier
+* Debug module that logs every step.
+* no setters in Contract#setup
 
 vererben in inline representern (module zum einmixen, attrs löschen)
 
 # TODO: remove the concept of Errors#messages and just iterate over Errors.
 # each form contains its local field errors in Errors
-# form.messages should then go through them and compile a "summary" instead of adding them to the parents #errors in #validate.
+# form.messages should then go through them and compile a "summary" instead of adding them to the parents #errors in #validate.
+
+
+
+in a perfect world, a UI form would send JSON as in the API. that's why the reform form creates the correct object graph first, then validates. creating the graph usually happens in the API representer code.
+
+
+WHY DON'T PEOPLE USE THIS:
+http://guides.rubyonrails.org/association_basics.html#the-has-many-association
+4.2.2.2 :autosave
+
+If you set the :autosave option to true, Rails will save any loaded members and destroy members that are marked for destruction whenever you save the parent object.

data/lib/reform.rb

@@ -1,7 +1,15 @@
+module Reform
+  autoload :Contract, 'reform/contract'
+
+  def self.rails3_0?
+    ::ActiveModel::VERSION::MAJOR == 3 and ::ActiveModel::VERSION::MINOR == 0
+  end
+end
+
 require 'reform/form'
 require 'reform/form/composition'
 require 'reform/form/active_model'
 
 if defined?(Rails) # DISCUSS: is everyone ok with this?
   require 'reform/rails'
-end
+end

data/lib/reform/composition.rb

@@ -1,54 +1,61 @@
+require 'disposable/composition'
+
 module Reform
-  # Keeps composition of models and knows how to transform a plain hash into a nested hash.
-  class Composition
-    class << self
-      def map(options)
-        @attr2obj = {}  # {song: ["title", "track"], artist: ["name"]}
+  class Expose
+    include Disposable::Composition
 
-        options.each do |mdl, meths|
-          create_accessors(mdl, meths)
-          attr_reader mdl
+    # DISCUSS: this might be moved to Disposable::Twin::Expose.
+    class << self
+      # Builder for a concrete Composition class with configurations from the form's representer.
+      def from(representer)
+        options = {}
 
-          meths.each { |m| @attr2obj[m.to_s] = mdl }
+        representer.representable_attrs.each do |definition|
+          process_definition!(options, definition)
         end
-      end
 
-      # Specific to representable.
-      def map_from(representer)
-        options = {}
-        representer.representable_attrs.each do |cfg|
-          options[cfg.options[:on]] ||= []
-          options[cfg.options[:on]] << cfg.name
+        Class.new(self).tap do |composition| # for 1.8 compat. you're welcome.
+          composition.map(options)
+          # puts composition@map.inspect
         end
-
-        map options
       end
 
-      def model_for_property(name)
-        @attr2obj.fetch(name.to_s)
+    private
+      def process_definition!(options, definition)
+        options[:model] ||= []
+        options[:model] << [definition[:private_name], definition.name].compact
       end
+    end
+  end
 
-    private
-      def create_accessors(model, methods)
-        accessors = methods.collect { |m| [m, "#{m}="] }.flatten
-        delegate *accessors << {:to => :"#{model}"}
+  # Keeps composition of models and knows how to transform a plain hash into a nested hash.
+  class Composition < Expose
+
+    # DISCUSS: this might be moved to Disposable::Twin::Composition.
+    class << self
+      # Builder for a concrete Composition class with configurations from the form's representer.
+      def process_definition!(options, definition)
+        options[definition[:on]] ||= []
+        options[definition[:on]] << [definition[:private_name], definition.name].compact
       end
     end
 
-    # TODO: make class method?
+    def save
+      each { |model| model.save }
+    end
+
     def nested_hash_for(attrs)
       {}.tap do |hsh|
         attrs.each do |name, val|
-          obj = self.class.model_for_property(name)
-          hsh[obj] ||= {}
-          hsh[obj][name.to_sym] = val
-        end
-      end
-    end
+          #obj = self.class.model_for_property(name)
+          config = self.class.instance_variable_get(:@map)[name.to_sym]
 
-    def initialize(models)
-      models.each do |name, obj|
-        instance_variable_set(:"@#{name}", obj)
+          model  = config[:model]
+          method = config[:method]
+
+          hsh[model] ||= {}
+          hsh[model][method] = val
+        end
       end
     end
   end