liaison 0.0.1

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+*swp

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in liaison.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,30 @@
+Copyright (c)2011, Mike Burns
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+
+    * Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the following
+      disclaimer in the documentation and/or other materials provided
+      with the distribution.
+
+    * Neither the name of Mike Burns nor the names of other
+      contributors may be used to endorse or promote products derived
+      from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,116 @@
+Liaison
+=======
+
+A Rails presenter class.
+
+A major idea of [the presenter pattern](http://blog.jayfields.com/2007/03/rails-presenter-pattern.html) is to break off the business logic from the view object, letting the view logic be a dumb instance that knows how to get, set, and validate values. The business logic can then query the presenter object for the values as needed.
+
+Look, here's an example business object:
+
+    class SignUp
+      attr_reader :user
+
+      def initialize(presenter, account_builder = Account)
+        @email        = presenter[:email]
+        @password     = presenter[:password]
+        @account_name = presenter[:account_name]
+    
+        @presenter       = presenter
+        @account_builder = account_builder
+      end
+    
+      def save
+        if presenter.valid?
+          account = account_builder.new(:name => account_name)
+          @user = account.users.build(:email => email, :password => password)
+          account.save.tap do |succeeded|
+            presenter.add_errors(account.errors) unless succeeded
+          end
+        end
+      end
+    
+      protected
+    
+      attr_accessor :email, :password, :account_name, :account_builder, :presenter
+    end
+
+It's just a class, which you can unit test as you please. A presenter object is passed in, then we pull the values out, make sure it's valid, and add errors to it as needed. This class does not deal directly with validations, state, or any of the ActiveModel nonsense.
+
+Now you need to know how to use a `Presenter` object, so this is what the controller looks like:
+
+    class SignupsController < ApplicationController
+      def new
+        @sign_up = presenter
+      end
+    
+      def create
+        @sign_up = presenter.with_params(params[:sign_up])
+        db = SignUp.new(@sign_up)
+    
+        if db.save
+          sign_in_as(db.user)
+          redirect_to root_url
+        else
+          render :new
+        end
+      end
+      
+      protected
+      
+      def presenter
+        Presenter.new('sign_up',
+                      :fields => [:email, :password, :account_name],
+                      :validator => SignUpValidator.new)
+      end
+    end
+
+In our `new` action we simply set the `@sign_up` i-var to an instance of the `Presenter`. In `create` we use that `Presenter` instance, adding CGI params in. Then we pass that to the `SignUp` class defined above and it's all boring from there.
+
+The `presenter` method in the above example produces a new `Presenter` instance. This instance has a model name (`sign_up`), fields the form will handle (`email`, `password`, and `account_name`), and a validator (`SignUpValidator`). The validator is any instance of `ActiveModel::Validator`, for example:
+
+    class SignUpValidator < ActiveModel::EachValidator
+      def validate_each(record, attribute, value)
+        record.errors.add(attribute, "can't be blank") if value.blank?
+      end
+    end
+
+You, the author of the business logic class, are in charge of checking in on these validations and errors. For example, before saving any objects you should check `Presenter#valid?`. And after you've saved something to the database you should add any errors onto the presenter using `Presenter#add_errors`.
+
+Getting Data
+----------
+
+An instance of the `Presenter` object is Hash-like: it implements the `Enumerable` module, which means it has an `#each` method among many others; it also has a `#[]` method, which you can use to access values just like with the CGI `params` hash.
+
+Testing
+-------
+
+When writing your unit tests it'll be handy to have a mock presenter around, which is why we package a `MockPresenter` class for you to use. It gives you access to the `#have_errors` and `#have_no_errors` RSpec matchers.
+
+
+    describe SignUp, 'invalid' do
+      let(:params) { { :email => '',
+                       :password => 'bar',
+                       :account_name => 'baz' } }
+      let(:errors) { { :email => "can't be blank" } }
+      let(:presenter) do
+        MockPresenter.new(:valid => false,
+                          :params => params,
+                          :errors => errors)
+      end
+      let(:account_builder) { MockAccount.new(:valid => true) }
+    
+      subject { SignUp.new(presenter, account_builder) }
+    
+      it "does not save the account or user" do
+        subject.save.should be_false
+
+        presenter.should have_errors(errors)
+      end
+    end
+
+Contact
+-------
+
+Copyright 2011 [Mike Burns](http://mike-burns.com/).
+
+Please [open a pull request on Github](https://github.com/mike-burns/liaison/pulls) as needed.

data/Rakefile

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

data/liaison.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "liaison/version"
+
+Gem::Specification.new do |s|
+  s.name        = "liaison"
+  s.version     = Liaison::VERSION
+  s.authors     = ["Mike Burns"]
+  s.email       = ["mike@mike-burns.com"]
+  s.homepage    = "https://github.com/mike-burns/liaison"
+  s.license     = 'BSD'
+  s.summary     = %q{A Rails presenter class.}
+  s.description = %q{An object that works with form_for that encapsulates validations and data management, leaving the business logic up to your testable old self.}
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_dependency('activemodel')
+
+  s.add_development_dependency('rspec')
+  s.add_development_dependency('rake')
+end

data/lib/liaison.rb

@@ -0,0 +1,3 @@
+require "liaison/version"
+require 'liaison/presenter'
+require 'liaison/mock_presenter'

data/lib/liaison/mock_presenter.rb

@@ -0,0 +1,31 @@
+class MockPresenter
+  def initialize(opts = {})
+    @valid = opts.delete(:valid) != false
+    @fields = opts[:params]
+    @errors = opts[:errors] || {}
+  end
+
+  def [](key)
+    @fields[key]
+  end
+
+  def valid?
+    @errors.empty? && @valid
+  end
+
+  def errors
+    @errors
+  end
+
+  def add_errors(errs)
+    errs.each {|k,v| @errors[k] = v}
+  end
+
+  def has_no_errors?
+    @errors.empty?
+  end
+
+  def has_errors?(errors)
+    errors.all? {|k,v| @errors[k] == v}
+  end
+end

data/lib/liaison/presenter.rb

@@ -0,0 +1,95 @@
+require 'active_model'
+
+class Presenter
+  extend ActiveModel::Naming
+  include ActiveModel::Conversion
+  include ActiveModel::Validations
+
+  validate :instance_validations
+
+  # Constructs a new Presenter object which can be passed to a form or
+  # generally filled with values. It must take a model name, which is a string
+  # that is the name of the model you are presenting. It can also take a
+  # validator and fields.
+  #
+  #   Presenter.new('sign_up',
+  #                 :fields => [:account_name, :email, :password],
+  #                 :validator => SignUpValidator)
+  def initialize(model_name, opts = {})
+    @@model_name = model_name
+
+    @validator = opts[:validator]
+    @fields   = opts[:fields]
+
+    self.class.send(:attr_accessor,*@fields) unless @fields.nil? || @fields.empty?
+  end
+
+  def instance_validations
+    validates_with(@validator, :attributes => @fields) if @validator
+  end
+
+  def self.model_name # :nodoc:
+    ActiveModel::Name.new(Class.new do
+      attr_reader :name
+      def initialize(n)
+        @name = n
+      end
+    end.new(@@model_name))
+  end
+
+  def persisted? # :nodoc:
+    false
+  end
+
+  # Set the params from the form using this.
+  #
+  #   @sign_up_presenter.with_params(params[:sign_up])
+  def with_params(params = {})
+    params.each {|k,v| self.send("#{k}=", v)}
+    self
+  end
+
+  # Combine error messages from any ActiveModel object with the presenter's, so
+  # they will show on the form.
+  #
+  #   @sign_up_presenter.add_errors(account.errors)
+  #
+  # You will probably use it like this:
+  #
+  #   class SignUp
+  #     attr_accessor :presenter
+  #     def save
+  #       account = Account.new
+  #       account.save.tap do |succeeded|
+  #         presenter.add_errors(account.errors) unless succeeded
+  #       end
+  #     end
+  #   end
+  def add_errors(errs)
+    errs.each {|k,v| errors.add(k,v)}
+  end
+
+  # Access individual values as if this were the CGI params hash.
+  #
+  #   @sign_up_presenter[:account_name]
+  def [](key)
+    to_hash[key]
+  end
+
+  # This is an instance of Enumerable, which means you can iterate over the
+  # keys and values as set by the form.
+  #
+  #   @sign_up_presenter.each {|k,v| puts "the form set #{k} to #{v}" }
+  def each(&block)
+    to_hash.each(&block)
+  end
+
+  protected
+
+  def to_hash
+    @fields.inject({}) do |acc,field|
+      acc[field] = send(field)
+      acc
+    end
+  end
+end

data/lib/liaison/version.rb

@@ -0,0 +1,3 @@
+module Liaison
+  VERSION = "0.0.1"
+end

data/spec/mock_presenter_spec.rb

@@ -0,0 +1,50 @@
+require 'spec_helper'
+
+describe MockPresenter, 'params' do
+  let(:params) {{'a' => 'one', 'b' => 'two'}}
+
+  subject { MockPresenter.new(:params => params) }
+
+  it "can access values using []" do
+    params.each do |k,v|
+      subject[k].should == v
+    end
+  end
+end
+
+describe MockPresenter, 'validations and errors' do
+  let(:errors) {{ :account_name => "can't be blank" }}
+
+  subject { MockPresenter.new(:valid => false, :errors => errors) }
+
+  it "is invalid with errors" do
+    subject.should_not be_valid
+    subject.errors.should_not be_blank
+    errors.each do |k,v|
+      subject.errors[k].should include(v)
+    end
+  end
+end
+
+describe MockPresenter, 'adding errors' do
+  let(:errors) {{ :account_name => "can't be blank" }}
+
+  subject { MockPresenter.new }
+
+  it "can add errors" do
+    subject.add_errors(errors)
+
+    subject.should_not be_valid
+    subject.errors.should_not be_blank
+    errors.each do |k,v|
+      subject.errors[k].should include(v)
+    end
+    subject.should have_errors(errors)
+  end
+
+  it "has no errors by default" do
+    subject.should be_valid
+    subject.errors.should be_blank
+    subject.should have_no_errors
+  end
+end

data/spec/presenter_spec.rb

@@ -0,0 +1,99 @@
+require 'spec_helper'
+
+describe Presenter do
+  let(:model_name) { 'sign_up' }
+
+  subject { Presenter.new(model_name) }
+
+  it "handles the ActiveModel naming" do
+    subject.class.model_name.singular.should == model_name
+  end
+
+  it "is an ActiveModel conversion" do
+    subject.should_not be_persisted
+    subject.to_model.should == subject
+    subject.to_key.should be_nil
+    subject.to_param.should be_nil
+  end
+end
+
+describe Presenter, 'validations' do
+  let(:model_name) { 'sign_up' }
+  let(:fields) { [:a, :b] }
+  let(:failing_validator) do
+    Class.new(ActiveModel::Validator) do
+      def initialize(opts)
+        @@attributes = opts[:attributes]
+        super(opts)
+      end
+
+      def validate(record)
+        record.errors[:base] << 'invalid'
+      end
+
+      def self.has_set_attributes_to?(attribs)
+        @@attributes == attribs
+      end
+    end
+  end
+  let(:succeeding_validator) do
+    Class.new(ActiveModel::Validator) do
+      def validate(record)
+        nil
+      end
+    end
+  end
+  let(:errors) { {:name => "can't be blank"} }
+
+  it "is valid by default" do
+    presenter = Presenter.new(model_name)
+    presenter.should be_valid
+    presenter.errors.should be_empty
+  end
+
+  it "runs validations as given" do
+    presenter = Presenter.new(model_name,
+                              :validator => failing_validator,
+                              :fields => fields)
+    presenter.should be_invalid
+    presenter.errors.should_not be_empty
+    failing_validator.should have_set_attributes_to(fields)
+  end
+
+  it "runs validations as given" do
+    presenter = Presenter.new(model_name, :validator => succeeding_validator)
+    presenter.should be_valid
+    presenter.errors.should be_empty
+  end
+
+  it "adds errors" do
+    presenter = Presenter.new(model_name)
+    presenter.add_errors(errors)
+    presenter.errors.should_not be_blank
+    errors.each do |k,v|
+      presenter.errors[k].should include(v)
+    end
+  end
+end
+
+describe Presenter, "enumerations" do
+  let(:model_name) { 'sign_up' }
+  subject do
+    Presenter.
+      new(model_name, :fields => [:a,:b]).
+      with_params('a' => 'hello', 'b' => 'goodbye')
+  end
+
+  it "eaches" do
+    subject.each do |k,v|
+      fail unless [:a,:b].include?(k)
+      v.should == 'hello' if k == :a
+      v.should == 'goodbye' if k == :b
+    end
+  end
+
+  it "is indexable" do
+    subject[:a].should == 'hello'
+    subject[:b].should == 'goodbye'
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1 @@
+require 'liaison'

metadata

@@ -0,0 +1,119 @@
+--- !ruby/object:Gem::Specification 
+name: liaison
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: 
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Mike Burns
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-09-10 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activemodel
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rake
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
+description: An object that works with form_for that encapsulates validations and data management, leaving the business logic up to your testable old self.
+email: 
+- mike@mike-burns.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- liaison.gemspec
+- lib/liaison.rb
+- lib/liaison/mock_presenter.rb
+- lib/liaison/presenter.rb
+- lib/liaison/version.rb
+- spec/mock_presenter_spec.rb
+- spec/presenter_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/mike-burns/liaison
+licenses: 
+- BSD
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.7.2
+signing_key: 
+specification_version: 3
+summary: A Rails presenter class.
+test_files: []
+