reform 0.0.1 → 0.1.0

data/CHANGES.md

@@ -0,0 +1,3 @@
+h3. 0.1.0
+
+* Oh yeah.

data/README.md

@@ -1,29 +1,170 @@
 # Reform
 
-TODO: Write a gem description
+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.
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add this line to your Gemfile:
 
-    gem 'reform'
+```ruby
+gem 'reform'
+```
 
-And then execute:
+## Defining Forms
 
-    $ bundle
+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?
 
-Or install it yourself as:
+```ruby
+class SongRequestForm < Reform::Form
+  include DSL
 
-    $ gem install reform
+  property :title,  on: :song
+  property :name,   on: :artist
 
-## Usage
+  validates :name, :title, presence: true
+end
+```
 
-TODO: Write usage instructions here
+The `::property` method allows defining the fields of the form. Using `:on` delegates this field to a nested object in your form.
 
-## Contributing
+__Note__: There is a convenience method `::properties` that allows you to pass an array of fields at one time.
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+## 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
+```
+
+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
+```
+
+## Rendering Forms
+
+Your `@form` is now ready to be rendered, either do it yourself or use something like `simple_form`.
+
+```haml
+= simple_form_for @form do |f|
+
+  = f.input :name
+  = f.input :title
+```
+
+## Validating Forms
+
+After a form submission, you wanna validate the input.
+
+```ruby
+def create
+  @form = SongRequestForm.new(song: Song.new, artist: Artist.new)
+
+  #=> params: {song_request: {title: "Rio", name: "Duran Duran"}}
+
+  if @form.validate(params[:song_request])
+```
+
+`Reform` uses the validations you provided in the form - and nothing else.
+
+
+## Saving Forms
+
+We provide a bullet-proof way to save your form data: by letting _you_ do it!
+
+```ruby
+  if @form.validate(params[:song_request])
+
+    @form.save do |data, nested|
+      #=> data:   <title: "Rio", name: "Duran Duran">
+      #
+      #   nested: {song:   {title: "Rio"},
+      #            artist: {name: "Duran Duran"}}
+
+      SongRequest.new(nested[:song][:title])
+    end
+```
+
+While `data` gives you an object exposing the form property readers, `nested` already reflects the nesting you defined in your form earlier.
+
+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=.
+```
+
+## ActiveModel - Rails Integration
+
+Reform offers ActiveModel support to easily make this accessible in Rails based projects.  You simply `include Reform::Form::ActiveModel` in your form object and the Rails specific code will be handled for you.
+
+### Simple Integration
+#### Form Class
+
+You have to include a call to `model` to specifiy which is the main object of the form.
+
+```ruby
+class UserProfileForm < Reform::Form
+  include DSL
+  include Reform::Form::ActiveModel
+
+  property :email,        on: :user
+  properties [:gender, :age],   on: :profile
+
+  model :user, on: :user
+
+  validates :email, :gender, presence: true
+  validates :age, numericality: true
+end
+```
+
+#### View Form
+
+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.
+
+```erb
+<%= form_for @form do |f| %>
+  <%= f.email_field :email %>
+  <%= f.input :gender %>
+  <%= f.number_field :age %>
+  <%= f.submit %>
+<% end %>
+```
+
+#### Controller
+
+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.
+
+```ruby
+class UsersController < ApplicationController
+
+  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
+
+
+  private
+  def create_new_form
+    UserProfileForm.new(user: User.new, profile: UserProfile.new)
+  end
+end
+```
+
+__Note__: this can also be used for the update action as well.
+
+## 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.

data/Rakefile

@@ -1 +1,9 @@
 require "bundler/gem_tasks"
+require 'rake/testtask'
+
+task :default => [:test]
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'test'
+  test.test_files = FileList['test/*_test.rb']
+  test.verbose = true
+end

data/lib/reform/form/active_model.rb

@@ -0,0 +1,28 @@
+module Reform::Form::ActiveModel
+  def self.included(base)
+    base.class_eval do
+      extend ClassMethods
+    end
+  end
+
+  module ClassMethods
+    def model(*args)
+      @model_options  = args  # FIXME: make inheritable!
+      main_model      = args.last[:on]
+
+      delegate main_model, :to => :model  # #song => model.song
+      delegate "persisted?", :to_key, :to_param, :to => main_model  # #to_key => song.to_key
+
+      alias_method args.first, main_model # #hit => model.song.
+    end
+
+    def property(name, options={})
+      delegate options[:on], :to => :model
+      super
+    end
+
+    def model_name
+      ActiveModel::Name.new(self, nil, @model_options.first.to_s.camelize)
+    end
+  end
+end

data/lib/reform/form/dsl.rb

@@ -0,0 +1,38 @@
+class Reform::Form
+  module DSL
+    def self.included(base)
+      base.class_eval do
+        extend ClassMethods
+      end
+    end
+
+    module ClassMethods
+      def property(name, *args)
+        representer_class.property(name, *args)
+      end
+
+      def properties(names, *args)
+        names.each do |name|
+          property(name, *args)
+        end
+      end
+
+    #private
+      def representer_class
+        @representer_class ||= Class.new(Reform::Representer)
+      end
+
+      def model_class
+        rpr = representer_class
+        @model_class ||= Class.new(Reform::Composition) do
+          map_from rpr
+        end
+      end
+    end
+
+    def initialize(models)
+      composition = self.class.model_class.new(models)
+      super(self.class.representer_class, composition)
+    end
+  end
+end

data/lib/reform/form.rb

@@ -0,0 +1,132 @@
+require 'delegate'
+
+module Reform
+  class Form  < SimpleDelegator
+    # reasons for delegation:
+    # presentation: this object is used in the presentation layer by #form_for.
+    # problem: #form_for uses respond_to?(:email_before_type_cast) which goes to an internal hash in the actual record.
+    # validation: this object also contains the validation rules itself, should be separated.
+    # TODO: figure out #to_key issues.
+
+    def initialize(mapper, composition)
+      @mapper     = mapper
+      @model      = composition
+      representer = @mapper.new(composition)
+
+      super Fields.new(representer.fields, representer.to_hash)  # decorate composition and transform to hash.
+    end
+
+    def validate(params)
+      # here it would be cool to have a validator object containing the validation rules representer-like and then pass it the formed model.
+      update_with(params)
+
+      valid?  # this validates on <Fields> using AM::Validations, currently.
+    end
+
+    def save
+      # DISCUSS: we should never hit @mapper here (which writes to the models) when a block is passed.
+      return yield self, to_nested_hash if block_given?
+
+      @mapper.new(model).from_hash(to_hash) # DISCUSS: move to Composition?
+    end
+
+  private
+    attr_accessor :mapper, :model
+
+    def update_with(params)
+      mapper.new(self).from_hash(params) # sets form properties found in params on self.
+    end
+
+    # Use representer to return current key-value form hash.
+    def to_hash
+      mapper.new(self).to_hash
+    end
+
+    def to_nested_hash
+      model.nested_hash_for(to_hash)  # use composition to compute nested hash.
+    end
+
+    # FIXME: make AM optional.
+    require 'active_model'
+    include ActiveModel::Validations
+  end
+
+  # Keeps values of the form fields. What's in here is to be displayed in the browser!
+  # we need this intermediate object to display both "original values" and new input from the form after submitting.
+  class Fields < OpenStruct
+    def initialize(properties, values={})
+      fields = properties.inject({}) { |hsh, attr| hsh.merge!(attr => nil) }
+      super(fields.merge!(values))  # TODO: stringify value keys!
+    end
+  end
+
+  # 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 # FIXME: unless already defined!!
+
+          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
+
+  require 'representable/hash'
+  class Representer < Representable::Decorator
+    include Representable::Hash
+
+    def self.properties(names, *args)
+      names.each do |name|
+        property(name, *args)
+      end
+    end
+
+    # Returns hash of all property names.
+    def fields
+      representable_attrs.collect { |cfg| cfg.name }
+    end
+  end
+end

data/lib/reform/version.rb

@@ -1,3 +1,3 @@
 module Reform
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end

data/lib/reform.rb

@@ -3,3 +3,7 @@ require "reform/version"
 module Reform
   # Your code goes here...
 end
+
+require 'reform/form'
+require 'reform/form/dsl'
+require 'reform/form/active_model'

data/reform.gemspec

@@ -6,8 +6,8 @@ require 'reform/version'
 Gem::Specification.new do |spec|
   spec.name          = "reform"
   spec.version       = Reform::VERSION
-  spec.authors       = ["Nick Sutterer"]
-  spec.email         = ["apotonick@gmail.com"]
+  spec.authors       = ["Nick Sutterer", "Garrett Heinlen"]
+  spec.email         = ["apotonick@gmail.com", "heinleng@gmail.com"]
   spec.description   = %q{Freeing your AR models from form logic.}
   spec.summary       = %q{Freeing your AR models from form logic.}
   spec.homepage      = ""
@@ -18,6 +18,9 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_dependency             "representable"
+  spec.add_development_dependency "bundler",        "~> 1.3"
   spec.add_development_dependency "rake"
+  spec.add_development_dependency "minitest"
+  spec.add_development_dependency "activemodel"
 end

data/test/dsl_test.rb

@@ -0,0 +1,72 @@
+require 'test_helper'
+
+class DslTest < MiniTest::Spec
+  class SongForm < Reform::Form
+    include DSL
+
+    property  :title,  :on => :song
+    properties [:name, :genre],   :on => :artist
+
+    validates :name, :title, :genre, presence: true
+  end
+
+  let (:form) { SongForm.new(:song => OpenStruct.new(:title => "Rio"), :artist => OpenStruct.new()) }
+
+  it "works by creating Representer and Composition for you" do
+    form.validate("title" => "Greyhound", "name" => "Frenzal Rhomb").must_equal false
+  end
+end
+
+class ActiveModelTest < MiniTest::Spec
+   class HitForm < Reform::Form
+    include DSL
+    include Reform::Form::ActiveModel
+
+    property  :title,  :on => :song
+    properties [:name, :genre],   :on => :artist
+
+    model :hit, :on => :song
+  end
+
+  let (:rio) { OpenStruct.new(:title => "Rio") }
+  let (:duran) { OpenStruct.new }
+  let (:form) { HitForm.new(:song => rio, :artist => duran) }
+
+  it "creates model readers" do
+    form.hit.must_equal rio
+  end
+
+  it "creates composition readers" do
+    form.song.must_equal rio
+    form.artist.must_equal duran
+  end
+
+  it "provides ::model_name" do
+    form.class.model_name.must_equal "Hit"
+  end
+
+  it "provides #persisted?" do
+    HitForm.new(:song => OpenStruct.new.instance_eval { def persisted?; "yo!"; end; self }, :artist => OpenStruct.new).persisted?.must_equal "yo!"
+  end
+
+  it "provides #to_key" do
+    HitForm.new(:song => OpenStruct.new.instance_eval { def to_key; "yo!"; end; self }, :artist => OpenStruct.new).to_key.must_equal "yo!"
+  end
+
+  it "provides #to_param" do
+    HitForm.new(:song => OpenStruct.new.instance_eval { def to_param; "yo!"; end; self }, :artist => OpenStruct.new).to_param.must_equal "yo!"
+  end
+
+  it "works with any order of ::model and ::property" do
+    class AnotherForm < Reform::Form
+      include DSL
+      include Reform::Form::ActiveModel
+
+      model :song, :on => :song
+      property  :title,  :on => :song
+    end
+
+
+    AnotherForm.new(:song => rio).song.must_equal rio
+  end
+end

data/test/reform_test.rb

@@ -0,0 +1,203 @@
+require 'test_helper'
+
+class RepresenterTest < MiniTest::Spec
+  class SongRepresenter < Reform::Representer
+    properties [:title, :year]
+  end
+
+  let (:rpr) { SongRepresenter.new(OpenStruct.new(:title => "Disconnect, Disconnect", :year => 1990)) }
+
+  # TODO: introduce representer_for helper.
+  describe "::properties" do
+    it "accepts array of property names" do
+      rpr.to_hash.must_equal({"title"=>"Disconnect, Disconnect", "year" => 1990} )
+    end
+  end
+
+  describe "#fields" do
+    it "returns all properties as strings" do
+      rpr.fields.must_equal(["title", "year"])
+    end
+  end
+end
+
+class FieldsTest < MiniTest::Spec
+  describe "#new" do
+    it "accepts list of properties" do
+      fields = Reform::Fields.new([:name, :title])
+      fields.name.must_equal  nil
+      fields.title.must_equal nil
+    end
+
+    it "accepts list of properties and values" do
+      fields = Reform::Fields.new(["name", "title"], "title" => "The Body")
+      fields.name.must_equal  nil
+      fields.title.must_equal "The Body"
+    end
+
+    it "processes value syms" do
+      fields = Reform::Fields.new(["name", "title"], :title => "The Body")
+      fields.name.must_equal  nil
+      fields.title.must_equal "The Body"
+    end
+  end
+end
+
+class ReformTest < MiniTest::Spec
+  let (:duran)  { OpenStruct.new(:name => "Duran Duran") }
+  let (:rio)    { OpenStruct.new(:title => "Rio") }
+
+  let (:form) { SongForm.new(SongAndArtistMap, comp) }
+
+  class SongAndArtistMap < Reform::Representer
+    property :name, on: :artist
+    property :title, on: :song
+  end
+
+  class SongForm < Reform::Form
+  end
+
+  describe "Composition" do
+    class SongAndArtist < Reform::Composition
+      map({:artist => [:name], :song => [:title]}) #SongAndArtistMap.representable_attrs
+    end
+
+    let (:comp) { SongAndArtist.new(:artist => @artist=OpenStruct.new, :song => rio) }
+
+    it "delegates to models as defined" do
+      comp.name.must_equal nil
+      comp.title.must_equal "Rio"
+    end
+
+    it "raises when non-mapped property" do
+      assert_raises NoMethodError do
+        comp.raise_an_exception
+      end
+    end
+
+    it "creates readers to models" do
+      comp.song.object_id.must_equal rio.object_id
+      comp.artist.object_id.must_equal @artist.object_id
+    end
+
+    describe "::map_from" do
+      it "creates the same mapping" do
+        comp =
+        Class.new(Reform::Composition) do
+          map_from SongAndArtistMap
+        end.
+        new(:artist => duran, :song => rio)
+
+        comp.name.must_equal "Duran Duran"
+        comp.title.must_equal "Rio"
+      end
+    end
+
+    describe "#nested_hash_for" do
+      it "returns nested hash" do
+        comp.nested_hash_for(:name => "Jimi Hendrix", :title => "Fire").must_equal({:artist=>{:name=>"Jimi Hendrix"}, :song=>{:title=>"Fire"}})
+      end
+
+      it "works with strings" do
+        comp.nested_hash_for("name" => "Jimi Hendrix", "title" => "Fire").must_equal({:artist=>{:name=>"Jimi Hendrix"}, :song=>{:title=>"Fire"}})
+      end
+
+      it "works with strings in map" do
+        Class.new(Reform::Composition) do
+          map(:artist => ["name"])
+        end.new([nil]).nested_hash_for(:name => "Jimi Hendrix").must_equal({:artist=>{:name=>"Jimi Hendrix"}})
+      end
+    end
+  end
+
+  describe "(new) form with empty models" do
+    let (:comp) { SongAndArtist.new(:artist => OpenStruct.new, :song => OpenStruct.new) }
+
+    it "returns empty fields" do
+      form.title.must_equal nil
+      form.name.must_equal  nil
+    end
+
+    describe "and submitted values" do
+      it "returns filled-out fields" do
+        form.validate("name" => "Duran Duran")
+
+        form.title.must_equal nil
+        form.name.must_equal  "Duran Duran"
+      end
+    end
+  end
+
+  describe "(edit) form with existing models" do
+    let (:comp) { SongAndArtist.new(:artist => duran, :song => rio) }
+
+    it "returns filled-out fields" do
+      form.name.must_equal  "Duran Duran"
+      form.title.must_equal "Rio"
+    end
+  end
+
+  describe "#validate" do
+    let (:comp) { SongAndArtist.new(:artist => OpenStruct.new, :song => OpenStruct.new) }
+
+    it "ignores unmapped fields in input" do
+      form.validate("name" => "Duran Duran", :genre => "80s")
+      assert_raises NoMethodError do
+        form.genre
+      end
+    end
+
+    it "returns true when valid" do
+      form.validate("name" => "Duran Duran").must_equal true
+    end
+
+    # TODO: test errors. test valid.
+    it "returns false when invalid" do
+      class ValidatingForm < Reform::Form
+        validates :name, :presence => true
+      end
+
+      ValidatingForm.new(SongAndArtistMap, comp).validate({}).must_equal false
+    end
+  end
+
+
+  describe "#save" do
+    let (:comp) { SongAndArtist.new(:artist => OpenStruct.new, :song => OpenStruct.new) }
+    let (:form) { SongForm.new(SongAndArtistMap, comp) }
+
+    before { form.validate("name" => "Diesel Boy") }
+
+    it "pushes data to models" do
+      form.save
+
+      comp.artist.name.must_equal "Diesel Boy"
+      comp.song.title.must_equal nil
+    end
+
+    describe "#save with block" do
+      it "provides data block argument" do
+        hash = {}
+
+        form.save do |data, map|
+          hash[:name]   = data.name
+          hash[:title]  = data.title
+        end
+
+        hash.must_equal({:name=>"Diesel Boy", :title=>nil})
+      end
+
+      it "provides nested symbolized hash as second block argument" do
+        hash = {}
+
+        form.save do |data, map|
+          hash = map
+        end
+
+        hash.must_equal({:artist=>{:name=>"Diesel Boy"}})
+      end
+    end
+  end
+end
+
+# TODO: test errors

data/test/test_helper.rb

@@ -0,0 +1,4 @@
+require 'test/unit'
+require 'minitest/spec'
+require 'ostruct'
+require 'reform'

metadata

@@ -1,16 +1,33 @@
 --- !ruby/object:Gem::Specification
 name: reform
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
 - Nick Sutterer
+- Garrett Heinlen
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-30 00:00:00.000000000 Z
+date: 2013-05-09 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: representable
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -43,21 +60,61 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Freeing your AR models from form logic.
 email:
 - apotonick@gmail.com
+- heinleng@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- CHANGES.md
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
 - lib/reform.rb
+- lib/reform/form.rb
+- lib/reform/form/active_model.rb
+- lib/reform/form/dsl.rb
 - lib/reform/version.rb
 - reform.gemspec
+- test/dsl_test.rb
+- test/reform_test.rb
+- test/test_helper.rb
 homepage: ''
 licenses:
 - MIT
@@ -83,4 +140,7 @@ rubygems_version: 1.8.25
 signing_key: 
 specification_version: 3
 summary: Freeing your AR models from form logic.
-test_files: []
+test_files:
+- test/dsl_test.rb
+- test/reform_test.rb
+- test/test_helper.rb