forminate 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 98167c9f1b4bb61b66458c8166c6c1406dc29426
-  data.tar.gz: 5e6e5c08e0467967649dba74a28677b07353ef06
+  metadata.gz: f117e333af88c5257424675b2ba3b235a3a7e514
+  data.tar.gz: 6a5483b6310fdc7b46341d53f3dcd1f8382474df
 SHA512:
-  metadata.gz: 9d82544a8edb6a3a87d70d7ae76313942a73ce0242a618dcd55937dee533cfe1d3870001ca9614b4db8bf8f4f138f9aba167f55438ac1d8470d0b9b59622a74d
-  data.tar.gz: e156a1daa75023040fa9a04db1df13464d08a4afaba43718a9be20cbb7c35f0179e5e57bdb0d262b670a890a853d629be6890b5504591500fbfaef52cfad7c61
+  metadata.gz: 99a8d7568801c1732bbe22381569925e84da62555b8aa9edb1f2d3fa4fbb9bcd248c054db78414a868997d54dbff71cc2d5a9aa296585a9b63f7d238627bfeaa
+  data.tar.gz: 4eda18ed97e5a63be2fa985eafd15b403faf0640eefd5c2705dbc20c1a5c4d999f9e55ea1bf9d9de38182b650634c308e4c4369bb3f5dc5b6e319bb056d200ce

data/.travis.yml

@@ -2,5 +2,10 @@ language: ruby
 rvm:
   - 1.9.3
   - 2.0.0
-  - jruby-19mode
-  - rbx-19mode
+  - 2.1.0
+  - jruby
+  - rbx
+addons:
+  code_climate:
+    repo_token:
+      secure: AeJjEZpQ3k0FFhsjvSce9k8VBOjed5Qe0wd6PlRhO8Uuv73VZQTFScvHSV/p0BUNUYMAvvPFHD8ha2yaC0cbqKzdZVbgp3OLmv553CymlmEGdOZxhg5X7thnheAMF/SMxoqpB9X+MHDbQxnf6hYoa6ntWSpzh4bb7ruyR03sGYM=

data/Gemfile

@@ -2,3 +2,5 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in forminate.gemspec
 gemspec
+
+gem 'codeclimate-test-reporter', group: :test, require: nil

data/README.md

@@ -1,9 +1,19 @@
 # Forminate
 
-[![Build Status](https://travis-ci.org/molawson/forminate.png?branch=master)](https://travis-ci.org/molawson/forminate)
-[![Code Climate](https://codeclimate.com/github/molawson/forminate.png)](https://codeclimate.com/github/molawson/forminate)
+[![Build Status](https://img.shields.io/travis/molawson/forminate.svg)](https://travis-ci.org/molawson/forminate)
+[![Code Climate](https://img.shields.io/codeclimate/github/molawson/forminate.svg)](https://codeclimate.com/github/molawson/forminate)
+[![Code Climate Coverage](https://img.shields.io/codeclimate/coverage/github/molawson/forminate.svg)](https://codeclimate.com/github/molawson/forminate)
 
-TODO: Write a gem description
+Doing CRUD operations in Rails is pretty awesome. Just remember the first time you generated a Rails scaffold and almost immediately started creating and editing records in the database from a web form. I'd bet that hooked a lot of people. It certainly caught my attention.
+
+Before too long, you need to create a page in a Rails app that has to update multiple models from a single form. Now, you feel the pain.
+
+> Life is pain, Highness. Anyone who says differently is selling something.
+_— Man in Black_
+
+If you're at this point, let me introduce you to form objects. The general idea is that you create an object that represents the form you want to display in the view, and that form object handles aggregating and coordinating the various models that make up the form. For more information on the particulars of form objects and some example implementations in Rails, check out these great posts from [Code Climate](http://blog.codeclimate.com/blog/2012/10/17/7-ways-to-decompose-fat-activerecord-models/), [Thoughtbot](http://robots.thoughtbot.com/activemodel-form-objects), and [Pivotal Labs](http://pivotallabs.com/form-backing-objects-for-fun-and-profit/).
+
+_Forminate gives you a handy way to create form objects that inherit behavior from the models you need and have just enough of the behavior you'd expect from an ActiveRecord or ActiveAttr model to make working with them feel very familiar._
 
 ## Installation
 
@@ -21,7 +31,203 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+### Requirements
+
+Currently, forminate only works with ActiveRecord and [ActiveAttr](https://github.com/cgriego/active_attr) models. I would love to extend it to support other models (and it may actually work with others), but only these two have been tested.
+
+### Example
+
+To see how this works, lets take the classic example of a single page checkout process. We want to be able to have the user sign up and/or purchase a membership from a single form. We already have the following models in our system, all of which are needed on the checkout page.
+
+```ruby
+class Membership < ActiveRecord::Base
+  # database columns: name, price
+  validates_presence_of :name
+end
+
+class User < ActiveRecord::Base
+  # database columns: first_name, last_name, email
+  validates_presence_of :email
+  attr_accessor :temporary_note
+end
+
+class CreditCard
+  include ActiveAttr::Model
+
+  attribute :number
+  attribute :expiration
+  attribute :cvv
+
+  validates_presence_of :number, :expiration, :cvv
+  validates_length_of :number, in: 12..19
+end
+```
+
+To better model what's actually happening on the checkout page, we create a Cart form object that includes a user, membership, and credit_card.
+
+```ruby
+class Cart
+  include Forminate
+
+  attribute :total
+  attribute :tax
+
+  attributes_for :user
+  attributes_for :membership, validate: false
+  attributes_for :credit_card, validate: :require_credit_card?
+
+  validates_numericality_of :total
+
+  def require_credit_card?
+    membership.price && membership.price.to_f > 0.0
+  end
+end
+```
+
+This small class gives us a lot of nice features.
+
+### Attributes
+
+The heart and soul of forminate is the `.attributes_for` method. Calling that method does a couple of things.
+
+First, it sets up an association to an instance of the desired object, using the naming conventions you're used to in Rails, and exposes that object with reader and writer methods.
+
+```ruby
+cart = Cart.new
+cart.credit_card # => #<CreditCard number: nil, expiration: nil, cvv: nil>
+
+payment_card = CreditCard.new(number: 4242424242424242, expiration: 0115, cvv: 123)
+cart.credit_card = payment_card
+cart.credit_card # => #<CreditCard number: 4242424242424242, expiration: 0115, cvv: 123>
+```
+
+It also sets up reader and writer methods for all of the associated object's attributes To prevent method name conflicts, it prepends the underscore version of the model name.
+
+```ruby
+cart = Cart.new
+cart.credit_card_number # => nil
+cart.credit_card_number = 4242424242424242
+cart.credit_card_number # => 4242424242424242
+```
+
+Using these new attribute names, you can initialize your form object with a hash of attributes, just like ActiveRecord models.
+
+```ruby
+cart = Cart.new(credit_card_number: 4242424242424242, credit_card_expiration: 0115, credit_card_cvv: 123)
+cart.credit_card_number # => 4242424242424242
+cart.credit_card # => #<CreditCard number: 4242424242424242, expiration: 0115, cvv: 123>
+```
+
+#### Supported methods
+
+Forminate explicitly sets up reader and writer methods for accessing methods related to database columns for ActiveRecord models or attributes for ActiveAttr models.
+
+Additionally, you can call any method on an associated object via the form object by prepending the object's name, just like you do with other attributes. For example, the `User` class above has defined an `attr_accessor` for `temporary_note`.
+
+```ruby
+cart = Cart.new
+cart.user_temporary_note # => nil
+cart.user_temporary_note = "I won't be here long"
+cart.user_temporary_note # => "I won't be here long"
+```
+
+### Rails Forms
+
+Now that we've got all these handy methods defined, we can get back to building those Rails forms we all know and love.
+
+In your controller, you can create an instance variable for your form object like you would do with a normal model.
+
+```ruby
+class CartController < ApplicationController
+  def new
+    @cart = Cart.new
+  end
+end
+```
+
+Then, you can setup your form view just like you'd expect.
+
+```erb
+<%= form_for @cart, url: cart_path, method: :post do |f| %>
+  <div class="field">
+    <%= f.label :user_email %>
+    <%= f.text_field :user_email %>
+  </div>
+  <div class="field">
+    <%= f.label :user_first_name %>
+    <%= f.text_field :user_first_name %>
+  </div>
+  <div class="field">
+    <%= f.label :user_last_name %>
+    <%= f.text_field :user_last_name %>
+  </div>
+  <div class="field">
+    <%= f.label :credit_card_number %>
+    <%= f.text_field :credit_card_number %>
+  </div>
+  <div class="field">
+    <%= f.label :credit_card_cvv %>
+    <%= f.text_field :credit_card_cvv %>
+  </div>
+  <%# etc., etc. %>
+<% end %>
+```
+
+### Persistence
+
+Forminate coordinates all the persistence for you. It includes a `#save` method that persists all the associated objects that also respond to `#save`. As long as ActiveRecord is available, forminate will wrap it's save in a single transaction, so if any of the associated models fails to save, it will roll everything back.
+
+With this behavior, you can write your controller create actions just like you always have.
+
+```ruby
+class CartController < ApplicationController
+  def new
+    @cart = Cart.new
+  end
+
+  def create
+    @cart = Cart.new(params[:cart])
+    if @cart.save
+      flash[:notice] = 'All good.'
+      redirect_to root_url
+    else
+      flash[:alert] = 'Something went terribly wrong.'
+      render :new
+    end
+  end
+end
+```
+
+Forminate also exposes a `#before_save` hook method that can be used in your form object if you need to do any extra work just before the models are saved.
+
+### Validations
+
+By default, a forminate object will "inherit" all it's associated objects validations. Before saving it's associated objects, forminate will make sure that they're all valid. If not, it will return `false` and the form object will include an ActiveRecord-like errors object.
+
+When calling `.attributes_for` to setup an associated object, you can pass a hash of options, which can include a `:validate` key. The value of the `:validate` key can be either, `true`, `false`, or a symbol that matches the name of a method that should be called to determine whether or not the association's validation should be checked (This is very similar to the `:if` option for the `.validates` methods in Rails).
+
+From our example:
+
+```ruby
+class Cart
+  include Forminate
+
+  attribute :total
+  attribute :tax
+
+  attributes_for :user
+  attributes_for :membership, validate: false
+  attributes_for :credit_card, validate: :require_credit_card?
+
+  validates_numericality_of :total
+
+  def require_credit_card?
+    membership.price && membership.price.to_f > 0.0
+  end
+end
+```
+
+In this case, if the membership that's being purchased is "free", we'll skip the credit card validations, and we won't bother with the membership validations at all.
 
 ## Contributing
 

data/Rakefile

@@ -2,4 +2,4 @@ require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
-task :default => :spec
+task default: :spec

data/forminate.gemspec

@@ -4,25 +4,31 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'forminate/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "forminate"
+  spec.name          = 'forminate'
   spec.version       = Forminate::VERSION
-  spec.authors       = ["Mo Lawson"]
-  spec.email         = ["moklawson@gmail.com"]
-  spec.description   = "Form objects for Rails applications"
-  spec.summary       = "Create form objects from multiple Active Record and/or ActiveAttr models."
-  spec.homepage      = "https://github.com/molawson/forminate"
-  spec.license       = "MIT"
+  spec.authors       = ['Mo Lawson']
+  spec.email         = ['mo@molawson.com']
+  spec.description   = 'Form objects for Rails applications'
+  spec.summary       = 'Create form objects from multiple Active Record and/or ActiveAttr models.'
+  spec.homepage      = 'https://github.com/molawson/forminate'
+  spec.license       = 'MIT'
 
-  spec.files         = `git ls-files`.split($/)
+  spec.files         = `git ls-files`.split($INPUT_RECORD_SEPARATOR)
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
-  spec.require_paths = ["lib"]
+  spec.require_paths = ['lib']
 
-  spec.add_dependency "active_attr", "~> 0.8"
-  spec.add_dependency "activesupport", ">= 3.0.2", "< 4.1"
-  spec.add_dependency "client_side_validations", "~> 3.2"
+  spec.add_dependency 'active_attr', '~> 0.8'
+  spec.add_dependency 'activesupport', '>= 3.0.2', '< 4.1'
+  spec.add_dependency 'client_side_validations', '~> 3.2'
 
-  spec.add_development_dependency "bundler", "~> 1.3"
-  spec.add_development_dependency "rake"
-  spec.add_development_dependency "rspec", "~> 2.11"
+  spec.add_development_dependency 'bundler', '~> 1.3'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rspec', '~> 2.11'
+  spec.add_development_dependency 'activerecord', '~> 3.2'
+  if defined?(JRUBY_VERSION)
+    spec.add_development_dependency 'activerecord-jdbcsqlite3-adapter'
+  else
+    spec.add_development_dependency 'sqlite3'
+  end
 end

data/lib/forminate/association_builder.rb

@@ -0,0 +1,44 @@
+module Forminate
+  class AssociationBuilder
+    def initialize(name, attrs)
+      @name = name
+      @attrs = attrs
+    end
+
+    def build
+      if primary_key
+        object = klass.find(primary_key)
+        object.assign_attributes(association_attributes)
+        object
+      else
+        klass.new(association_attributes)
+      end
+    end
+
+    private
+
+    attr_reader :name, :attrs
+
+    def klass
+      name.to_s.classify.constantize
+    end
+
+    def prefix
+      "#{name}_"
+    end
+
+    def primary_key
+      return unless klass.respond_to?(:primary_key)
+
+      attrs["#{name}_#{klass.primary_key}".to_sym]
+    end
+
+    def association_attributes
+      relevant_attributes = attrs.select { |k, _| k =~ /^#{prefix}/ }
+      relevant_attributes.each_with_object({}) do |(name, definition), hash|
+        new_key = name.to_s.sub(prefix, '').to_sym
+        hash[new_key] = definition
+      end
+    end
+  end
+end

data/lib/forminate/association_definition.rb

@@ -0,0 +1,22 @@
+module Forminate
+  class AssociationDefinition
+    attr_reader :name
+
+    def initialize(name, options = {})
+      @name = name
+      @options = options
+    end
+
+    def attributes
+      name.to_s.classify.constantize.attribute_names
+    end
+
+    def validation_condition
+      options.fetch(:validate) { true }
+    end
+
+    private
+
+    attr_reader :options
+  end
+end

data/lib/forminate/client_side_validations.rb

@@ -71,7 +71,7 @@ module Forminate
     # validation hash.
     def association_validators
       associations.reduce({}) do |assoc_validators, (name, object)|
-        if should_validate_assoc?(name) && object.respond_to?(:_validators)
+        if validate_assoc?(name) && object.respond_to?(:_validators)
           object._validators.each do |attr, validators|
             new_validators = validators.reduce([]) do |new_validators, validator|
               new_validator = validator.dup

data/lib/forminate/version.rb

@@ -1,3 +1,3 @@
 module Forminate
-  VERSION = "0.1.0"
+  VERSION = '0.2.0'
 end

data/lib/forminate.rb

@@ -1,8 +1,11 @@
-require "forminate/version"
+require 'forminate/version'
 
 require 'active_support/concern'
 require 'active_attr'
 
+require 'forminate/association_definition'
+require 'forminate/association_builder'
+
 module Forminate
   extend ActiveSupport::Concern
   include ActiveAttr::Model
@@ -10,10 +13,10 @@ module Forminate
   included do
     validate do
       associations.each do |name, object|
-        if should_validate_assoc?(name) && object.respond_to?(:invalid?) && object.invalid?
-          object.errors.each do |field, messages|
-            errors["#{name}_#{field}".to_sym] = messages
-          end
+        next unless validate_assoc?(name) && object.respond_to?(:invalid?) && object.invalid?
+
+        object.errors.each do |field, messages|
+          errors["#{name}_#{field}".to_sym] = messages
         end
       end
     end
@@ -21,8 +24,7 @@ module Forminate
 
   module ClassMethods
     def attributes_for(name, options = {})
-      define_attributes name
-      define_association name, options
+      define_association(AssociationDefinition.new(name, options))
     end
 
     def association_names
@@ -35,42 +37,33 @@ module Forminate
 
     private
 
-    def define_attributes(association_name)
-      attributes = association_name.to_s.classify.constantize.attribute_names
-      attributes.each { |attr| define_attribute(attr, association_name) }
+    def define_association(assoc)
+      assoc.attributes.each { |attr| define_attribute(attr, assoc.name) }
+      association_names << assoc.name
+      association_validations[assoc.name] = assoc.validation_condition
+      send(:attr_accessor, assoc.name)
     end
 
-    def define_attribute(attr, assoc)
-      ActiveAttr::AttributeDefinition.new("#{assoc}_#{attr}").tap do |attribute_definition|
+    def define_attribute(attr, assoc_name)
+      ActiveAttr::AttributeDefinition.new("#{assoc_name}_#{attr}").tap do |attribute_definition|
         attribute_name = attribute_definition.name.to_s
         attributes[attribute_name] = attribute_definition
       end
-      define_attribute_reader(attr, assoc)
-      define_attribute_writer(attr, assoc)
+      define_attribute_reader(attr, assoc_name)
+      define_attribute_writer(attr, assoc_name)
     end
 
-    def define_attribute_reader(attr, assoc)
-      define_method("#{assoc}_#{attr}") do
-        send(assoc.to_sym).send(attr.to_sym)
+    def define_attribute_reader(attr, assoc_name)
+      define_method("#{assoc_name}_#{attr}") do
+        send(assoc_name.to_sym).send(attr.to_sym)
       end
     end
 
-    def define_attribute_writer(attr, assoc)
-      define_method("#{assoc}_#{attr}=") do |value|
-        send(assoc.to_sym).send("#{attr}=".to_sym, value)
+    def define_attribute_writer(attr, assoc_name)
+      define_method("#{assoc_name}_#{attr}=") do |value|
+        send(assoc_name.to_sym).send("#{attr}=".to_sym, value)
       end
     end
-
-    def define_association(name, options = {})
-      association_names << name
-      should_validate = if options.has_key?(:validate)
-                          options[:validate]
-                        else
-                          true
-                        end
-      association_validations[name] = should_validate
-      send(:attr_accessor, name)
-    end
   end
 
   def initialize(attributes = {})
@@ -78,10 +71,6 @@ module Forminate
     super
   end
 
-  def persisted?
-    false
-  end
-
   def association_names
     self.class.association_names
   end
@@ -128,69 +117,40 @@ module Forminate
 
   def build_associations(attributes)
     association_names.each do |association_name|
-      association = build_association(association_name, attributes)
+      association = AssociationBuilder.new(association_name, attributes).build
       instance_variable_set("@#{association_name}".to_sym, association)
     end
   end
 
-  def build_association(name, attributes)
-    association_attributes = attributes_for_association(name, attributes)
-    klass = name.to_s.classify.constantize
-
-    if klass.respond_to? :primary_key
-      primary_key = attributes["#{name}_#{klass.primary_key}".to_sym]
-    end
-
-    if primary_key
-      object = klass.find primary_key
-      object.assign_attributes association_attributes
-      object
-    else
-      klass.new association_attributes
-    end
-  end
-
-  def attributes_for_association(association_name, attributes)
-    prefix = "#{association_name}_"
-    relevant_attributes = attributes.select { |k, v| k =~ /#{prefix}/ }
-    relevant_attributes.reduce({}) do |hash, (name, definition)|
-      new_key = name.to_s.sub(prefix, '').to_sym
-      hash[new_key] = definition
-      hash
-    end
-  end
-
   def persist_associations
-    associations.each do |name, object|
-      object.save if object.respond_to? :save
-    end
+    associations.each { |_, object| object.save if object.respond_to?(:save) }
   end
 
-  def should_validate_assoc?(name)
-    method_name = assoc_validation_filter_method(name)
-    send(method_name)
+  def validate_assoc?(name)
+    send(assoc_validation_filter_method(name))
   end
 
   def assoc_validation_filter_method(name)
     filter = self.class.association_validations.fetch(name, true)
-    method_name = "should_validate_#{name}?".to_sym
     case filter
     when Symbol
       filter
     when TrueClass, FalseClass
+      method_name = "validate_#{name}?".to_sym
       self.class.send(:define_method, method_name) { filter }
       method_name
     else
-      raise NotImplementedError, "The attributes_for :validate option can only take a symbol, true, or false"
+      fail NotImplementedError, 'The attributes_for :validate option can only take a symbol, true, or false'
     end
   end
 
   def association_for_method(name)
-    assoc_name = association_names.find { |an| name.match /^#{an}_/ }
-    if assoc_name
-      assoc_method_name = name.to_s.sub("#{assoc_name}_", '').to_sym
-      assoc = send(assoc_name)
-      return assoc, assoc_method_name
-    end
+    assoc_name = association_names.find { |an| name.match(/^#{an}_/) }
+
+    return unless assoc_name
+
+    assoc_method_name = name.to_s.sub("#{assoc_name}_", '').to_sym
+    assoc = send(assoc_name)
+    return assoc, assoc_method_name
   end
 end

data/spec/forminate/association_builder_spec.rb

@@ -0,0 +1,56 @@
+require 'spec_helper'
+
+describe Forminate::AssociationBuilder do
+  let(:name) { 'dummy_book' }
+  let(:attrs) do
+    {
+      dummy_user_first_name: 'Mo',
+      dummy_book_title: 'The Hobbit'
+    }
+  end
+
+  subject { Forminate::AssociationBuilder.new(name, attrs) }
+
+  describe '#build' do
+    context 'non-ActiveRecord model' do
+      it 'populates the association with the given attributes' do
+        expect(subject.build.title).to eq('The Hobbit')
+      end
+    end
+
+    context 'ActiveRecord model' do
+      let(:name) { 'dummy_user' }
+
+      context 'primary key not present in attributes' do
+        it 'populates the association with the given attributes' do
+          expect(subject.build.first_name).to eq('Mo')
+        end
+      end
+
+      context 'primary key present in attributes' do
+        let(:user) do
+          DummyUser.create(
+            first_name: 'Mo',
+            last_name: 'Lawson',
+            email: 'mo@example.com'
+          )
+        end
+        let(:attrs) do
+          {
+            dummy_user_id: user.id,
+            dummy_user_first_name: 'Matthew',
+            dummy_book_title: 'The Hobbit'
+          }
+        end
+
+        it 'populates the association from the database' do
+          expect(subject.build.last_name).to eq('Lawson')
+        end
+
+        it 'overrides database values with passed in values' do
+          expect(subject.build.first_name).to eq('Matthew')
+        end
+      end
+    end
+  end
+end

data/spec/forminate/association_definition_spec.rb

@@ -0,0 +1,29 @@
+require 'spec_helper'
+
+describe Forminate::AssociationDefinition do
+  let(:options) { {} }
+
+  subject { Forminate::AssociationDefinition.new(DummyUser, options) }
+
+  describe '#attributes' do
+    it 'returns a list of attributes from the appropriate class' do
+      expect(subject.attributes).to eq(%w(id first_name last_name email))
+    end
+  end
+
+  describe '#validation_condition' do
+    context 'options hash does not contain :validate key' do
+      it 'returns true' do
+        expect(subject.validation_condition).to be_true
+      end
+    end
+
+    context 'options hash contains :validate key' do
+      let(:options) { { validate: :stars_aligned? } }
+
+      it 'returns the value' do
+        expect(subject.validation_condition).to eq(:stars_aligned?)
+      end
+    end
+  end
+end