reform 0.1.2 → 0.2.0

data/.gitignore

@@ -16,3 +16,4 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
+test/dummy/log/*.log

data/.travis.yml

@@ -2,7 +2,6 @@ language: ruby
 rvm:
   - 2.0.0
   - 1.9.3
-  - 1.8.7
 gemfile:
   - Gemfile
   - gemfiles/Gemfile.rails-3.0

data/CHANGES.md

@@ -1,3 +1,16 @@
+h3. 0.2.0
+
+* Added nested property and collection for `has_one` and `has_many` relationships. . Note that this currently works only 1-level deep.
+* Renamed `Reform::Form::DSL` to `Reform::Form::Composition` and deprecated `DSL`.
+* `require 'reform'` now automatically requires Rails stuff in a Rails environment. Mainly, this is the FormBuilder compatibility layer that is injected into `Form`. If you don't want that, only require 'reform/form'.
+* Composition now totally optional
+* `Form.new` now accepts one argument, only: the model/composition. If you want to create your own representer, inject it by overriding `Form#mapper`. Note that this won't create property accessors for you.
+* `Form::ActiveModel` no longer creates accessors to your represented models, e.g. having `property :title, on: :song` doesn't allow `form.song` anymore. This is because the actual model and the form's state might differ, so please use `form.title` directly.
+
+h3. 0.1.3
+
+* Altered `reform/rails` to conditionally load `ActiveRecord` code and created `reform/active_record`.
+
 h3. 0.1.2
 
 * `Form#to_model` is now delegated to model.

data/Gemfile

@@ -1,7 +1,5 @@
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in reform.gemspec
 gemspec
 
-gem 'rake', "10.1.0.beta3"
 #gem 'representable', path: "../representable"

data/README.md

@@ -2,6 +2,9 @@
 
 Decouple your models from forms. Reform gives you a form object with validations and nested setup of models. It is completely framework-agnostic and doesn't care about your database.
 
+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).
+
+
 ## Installation
 
 Add this line to your Gemfile:
@@ -12,47 +15,47 @@ gem 'reform'
 
 ## Defining Forms
 
-Say you need a form for song requests on a radio station. Internally, this would imply associating `songs` table and the `artists` table. You don't wanna reflect that in your web form, do you?
+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.
 
 ```ruby
-class SongRequestForm < Reform::Form
-  include DSL
-
-  property :title,  on: :song
-  property :name,   on: :artist
+class SongForm < Reform::Form
+  property :title
+  property :length
 
-  validates :name, :title, presence: true
+  validates :title,  presence: true
+  validates :length, numericality: true
 end
 ```
 
-The `::property` method allows defining the fields of the form. Using `:on` delegates this field to a nested object in your form.
+To add fields to the form use the `::property` method. Also, validations no longer go into the model but sit in the form.
 
-__Note__: There is a convenience method `::properties` that allows you to pass an array of fields at one time.
 
 ## Using Forms
 
 In your controller you'd create a form instance and pass in the models you wanna work on.
 
 ```ruby
-def new
-  @form = SongRequestForm.new(song: Song.new, artist: Artist.new)
-end
+class SongsController
+  def new
+    @form = SongForm.new(Song.new)
+  end
 ```
 
 You can also setup the form for editing existing items.
 
 ```ruby
-def edit
-  @form = SongRequestForm.new(song: Song.find(1), artist: Artist.find(2))
-end
+class SongsController
+  def edit
+    @form = SongForm.new(Song.find(1))
+  end
 ```
 
 ## Rendering Forms
 
-Your `@form` is now ready to be rendered, either do it yourself or use something like `simple_form`.
+Your `@form` is now ready to be rendered, either do it yourself or use something like Rails' `#form_for`, `simple_form` or `formtastic`.
 
 ```haml
-= simple_form_for @form do |f|
+= form_for @form do |f|
 
   = f.input :name
   = f.input :title
@@ -63,15 +66,16 @@ Your `@form` is now ready to be rendered, either do it yourself or use something
 After a form submission, you wanna validate the input.
 
 ```ruby
-def create
-  @form = SongRequestForm.new(song: Song.new, artist: Artist.new)
+class SongsController
+  def create
+    @form = SongForm.new(Song.new)
 
-  #=> params: {song_request: {title: "Rio", name: "Duran Duran"}}
+    #=> params: {song: {title: "Rio", length: "366"}}
 
-  if @form.validate(params[:song_request])
+    if @form.validate(params[:song])
 ```
 
-`Reform` uses the validations you provided in the form - and nothing else.
+Reform uses the validations you provided in the form - and nothing else.
 
 
 ## Saving Forms
@@ -79,143 +83,320 @@ def create
 We provide a bullet-proof way to save your form data: by letting _you_ do it!
 
 ```ruby
-  if @form.validate(params[:song_request])
+  if @form.validate(params[:song])
 
     @form.save do |data, nested|
-      #=> data:   <title: "Rio", name: "Duran Duran">
-      #
-      #   nested: {song:   {title: "Rio"},
-      #            artist: {name: "Duran Duran"}}
+      data.title  #=> "Rio"
+      data.length #=> "366"
+
+      nested      #=> {title: "Rio"}
 
-      SongRequest.new(nested[:song][:title])
+      Song.create(nested)
     end
 ```
 
-While `data` gives you an object exposing the form property readers, `nested` already reflects the nesting you defined in your form earlier.
+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.
 
 ```ruby
-    @form.save  #=> populates song and artist with incoming data
-                #   by calling @form.song.name= and @form.artist.title=.
+    @form.save  #=> populates song with incoming data
+                #   by calling @form.song.title= and @form.song.length=.
 ```
 
-## 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.
+## Nesting Forms: 1-1 Relations
 
-Be sure to add `virtus` to your Gemfile.
+Songs have artists to compose them. Let's say your `Song` model would implement that as follows.
 
 ```ruby
-require 'reform/form/coercion'
+class Song < ActiveRecord::Base
+  has_one :artist
+end
+```
+
+The edit form should allow changing data for artist and song.
+
+```ruby
+class SongForm < Reform::Form
+  property :title
+  property :length
 
-class SongRequestForm < Reform::Form
-  include DSL
-  include Reform::Form::Coercion
+  property :artist do
+    property :name
 
-  property :written_at,  on: :song, type: DateTime
+    validates :name, presence: true
+  end
+
+  #validates :title, ...
 end
+```
+
+See how simple nesting forms is? By passing a block to `::property` you can define another form nested into your main form.
+
+
+### has_one: Setup
+
+This setup's only requirement is having a working `Song#artist` reader.
+
+```ruby
+class SongsController
+  def edit
+    song = Song.find(1)
+    song.artist #=> <0x999#Artist title="Duran Duran">
+
+    @form = SongForm.new(song)
+  end
+```
+
+### has_one: Rendering
+
+When rendering this form you could use the form's accessors manually.
+
+```haml
+= text_field :title,         @form.title
+= text_field "artist[name]", @form.artist.name
+```
 
+Or use something like `#fields_for` in a Rails environment.
+
+```haml
+= form_for @form |f|
+  = f.text_field :title
+  = f.text_field :length
+
+  = fields_for :artist do |a|
+    = a.text_field :name
+```
+
+### has_one: Processing
+
+The block form of `#save` would give you the following data.
+
+```ruby
 @form.save do |data, nested|
-  data.written_at #=> <DateTime XXX>
+  data.title #=> "Hungry Like The Wolf"
+  data.artist.name #=> "Duran Duran"
+
+  nested #=> {title:  "Hungry Like The Wolf",
+         #    artist: {name: "Duran Duran"}}
+end
 ```
 
-## Rails Integration
+Supposed you use reform's automatic save without a block, the following assignments would be made.
+
+```ruby
+form.song.title       = "Hungry Like The Wolf"
+form.song.artist.name = "Duran Duran"
+```
+
+## Nesting Forms: 1-n Relations
+
+Reform also gives you nested collections.
+
+Let's have Albums with songs!
+
+```ruby
+class Album < ActiveRecord::Base
+  has_many :songs
+end
+```
+
+The form might look like this.
+
+```ruby
+class AlbumForm < Reform::Form
+  property :title
+
+  collection :songs do
+    property :title
+
+    validates :title, presence: true
+  end
+end
+```
+
+This basically works like a nested `property` that iterates over a collection of songs.
+
+### has_many: Rendering
+
+Reform will expose the collection using the `#songs` method.
+
+```haml
+= text_field :title,         @form.title
+= text_field "songs[0][title]", @form.songs[0].title
+```
 
-[A sample Rails app using Reform.](https://github.com/gogogarrett/reform_example)
+However, `#fields_for` works just fine, again.
 
-Reform offers ActiveRecord support to easily make this accessible in Rails based projects. You simply `include Reform::Form::ActiveRecord` in your form object and the Rails specific code will be handled for you. This happens by adding behaviour to make the form ActiveModel-compliant. Note that this module will also work with other ORMs like Datamapper.
+```haml
+= form_for @form |f|
+  = f.text_field :title
+
+  = fields_for :songs do |s|
+    = s.text_field :title
+```
 
-### Simple Integration
-#### Form Class
+### has_many: Processing
 
-You have to include a call to `model` to specify which is the main object of the form.
+The block form of `#save` will expose the data structures already discussed.
 
 ```ruby
-require 'reform/rails'
+@form.save do |data, nested|
+  data.title #=> "Rio"
+  data.songs.first.title #=> "Hungry Like The Wolf"
+
+  nested #=> {title: "Rio"
+              songs: [{title: "Hungry Like The Wolf"},
+                     {title: "Last Chance On The Stairways"}]
+end
+```
 
-class UserProfileForm < Reform::Form
-  include DSL
-  include Reform::Form::ActiveRecord
 
-  property :email,        on: :user
-  properties [:gender, :age],   on: :profile
+## Compositions
 
-  model :user
+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.
 
-  validates :email, :gender, presence: true
-  validates :age, numericality: true
-  validates_uniqueness_of :email
+Say we were to edit a song and the label data the record was released from. Internally, this would imply working on the `songs` table and the `labels` table.
+
+```ruby
+class SongWithLabelForm < Reform::Form
+  include Composition
+
+  property :title, on: :song
+  property :city,  on: :label
+
+  validates :title, :city, presence: true
 end
 ```
 
-Basically, `model :user` tells Reform to use the `:user` object in the composition as the form main object while using `"user"` as the form name (needed for URL computation). If you want to change the form name let Reform know.
+Note that reform needs to know about the owner objects of properties. You can do so by using the `on:` option.
+
+### Composition: Setup
+
+The constructor slightly differs.
 
 ```ruby
-  model :singer, :on => :user # form name is "singer" whereas main object is `:user` in composition.
+@form = SongWithLabelForm.new(song: Song.new, label: Label.new)
 ```
 
+### Composition: Rendering
+
+After you configured your composition in the form, reform hides the fact that you're actually showing two different objects.
 
-#### View Form
+```haml
+= form_for @form do |f|
 
-The form becomes __very__ dumb as it knows nothing about the backend assocations or data binding to the database layer.  This simply takes input and passes it along to the controller as it should.
+  Song:     = f.input :title
 
-```erb
-<%= form_for @form do |f| %>
-  <%= f.email_field :email %>
-  <%= f.input :gender %>
-  <%= f.number_field :age %>
-  <%= f.submit %>
-<% end %>
+  Label in: = f.input :city
 ```
 
-#### Controller
+### Composition: Processing
+
+When using `#save' without a block reform will use writer methods on the different objects to push validated data to the properties.
 
-In the controller you can easily create helpers to build these form objects for you.  In the create and update actions Reform allows you total control of what to do with the data being passed via the form. How you interact with the data is entirely up to you.
+Here's how the block parameters look like.
 
 ```ruby
-class UsersController < ApplicationController
+@form.save do |data, nested|
+  data.title #=> "Rio"
+  data.city  #=> "London"
 
-  def create
-    @form = create_new_form
-    if @form.validate(params[:user])
-      @form.save do |data, map|
-        new_user = User.new(map[:user])
-        new_user.build_user_profile(map[:profile])
-        new_user.save!
-      end
-    end
-  end
+  nested #=> {
+              song:  {title: "Rio"}
+              label: {city: "London"}
+             }
+end
+```
 
+## Coercion
 
-  private
-  def create_new_form
-    UserProfileForm.new(user: User.new, profile: UserProfile.new)
-  end
+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.
+
+Be sure to add `virtus` to your Gemfile.
+
+```ruby
+require 'reform/form/coercion'
+
+class SongForm < Reform::Form
+  include Coercion
+
+  property :written_at, type: DateTime
 end
+
+@form.save do |data, nested|
+  data.written_at #=> <DateTime XXX>
 ```
 
-__Note__: this can also be used for the update action as well.
 
-## Using Your Models In Validations
+## Agnosticism: Mapping Data
+
+Reform doesn't really know whether it's working with a PORO, an `ActiveRecord` instance or a `Sequel` row.
+
+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.
+
+Nesting forms only requires readers for the nested properties as `Album#songs`.
+
+
+## Rails Integration
 
-Sometimes you want to access your database in a validation. You can access the models using the `#model` accessor in the form.
+Check out [@gogogarret](https://twitter.com/GoGoGarrett/)'s [sample Rails app](https://github.com/gogogarrett/reform_example) using Reform.
+
+Rails and Reform work out-of-the-box. If you're using Rails but for some reason wanna use the pure reform, `require reform/form`, only.
+
+
+## ActiveModel compliance
+
+Forms in Reform can easily be made ActiveModel-compliant.
+
+Note that this step is _not_ necessary in a Rails environment.
 
 ```ruby
-class ArtistForm < Reform::Form
-  property :name
+class SongForm < Reform::Form
+  include Reform::Form::ActiveModel
+end
+```
 
-  validate "name_correct?"
+If you're not happy with the `model_name` result, configure it manually.
 
-  def name_correct?
-    errors.add :name, "#{name} is stupid!" if model.artist.stupid_name?(name)
-  end
+```ruby
+class CoverSongForm < Reform::Form
+  include Reform::Form::ActiveModel
+
+  model :hit
 end
 ```
 
+This is especially helpful when your framework tries to render `cover_song_path` although you wanna go with `song_path`.
+
+
+## FormBuilder Support
+
+To make your forms work with all the form gems like `simple_form` or Rails `form_for` you need to include another module.
+
+Again, this step is implicit in Rails and you don't need to do it manually.
+
+```ruby
+class SongForm < Reform::Form
+  include Reform::Form::ActiveModel
+  include Reform::Form::ActiveModel::FormBuilderMethods
+end
+```
+
+
 ## Security
 
-By explicitely defining the form layout using `::property` there is no more need for protecting from unwanted input. `strong_parameter` or `attr_accessible` become obsolete. Reform will simply ignore undefined incoming parameters.
+By explicitely defining the form layout using `::property` there is no more need for protecting from unwanted input. `strong_parameter` or `
+attr_accessible` become obsolete. Reform will simply ignore undefined incoming parameters.
+
+
+## Support
+
+If you run into any trouble chat with us on irc.freenode.org#trailblazer.
+
 
 ## Maintainers
 
@@ -223,6 +404,7 @@ By explicitely defining the form layout using `::property` there is no more need
 
 [Garrett Heinlen](https://github.com/gogogarrett)
 
+
 ### 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.

data/Rakefile

@@ -7,3 +7,9 @@ Rake::TestTask.new(:test) do |test|
   test.test_files = FileList['test/*_test.rb']
   test.verbose = true
 end
+
+Rake::TestTask.new(:test_rails) do |test|
+  test.libs << 'test'
+  test.test_files = FileList['test/rails/*_test.rb']
+  test.verbose = true
+end

data/TODO.md

@@ -1,4 +1,13 @@
 * `validates :title, :presence => true`
   with @model.title == "Little Green Car" and validate({}) the form is still valid (as we "have" a valid title). is that what we want?
 
-* document Form#to_hash and Form#to_nested_hash (e.g. with OpenStruct composition to make it a very simple form)
+* document Form#to_hash and Form#to_nested_hash (e.g. with OpenStruct composition to make it a very simple form)
+
+* allow :as to rename nested forms
+* make #nested_forms easier
+
+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.

data/lib/reform/active_record.rb

@@ -0,0 +1,2 @@
+require 'reform/form/active_model'
+require 'reform/form/active_record'

data/lib/reform/composition.rb

@@ -0,0 +1,55 @@
+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"]}
+
+        options.each do |mdl, meths|
+          create_accessors(mdl, meths)
+          attr_reader mdl
+
+          meths.each { |m| @attr2obj[m.to_s] = mdl }
+        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
+        end
+
+        map options
+      end
+
+      def model_for_property(name)
+        @attr2obj.fetch(name.to_s)
+      end
+
+    private
+      def create_accessors(model, methods)
+        accessors = methods.collect { |m| [m, "#{m}="] }.flatten
+        delegate *accessors << {:to => :"#{model}"}
+      end
+    end
+
+    # TODO: make class method?
+    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
+
+    def initialize(models)
+      models.each do |name, obj|
+        instance_variable_set(:"@#{name}", obj)
+      end
+    end
+  end
+end