pardner 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 035c5bfe9bac013e8796c50a45cebc257120ef29
-  data.tar.gz: d0bacd7bfa3183c73a98b193160755151950e464
+  metadata.gz: 6c471837e73fc6705f1c119a78613061bfe1c5ac
+  data.tar.gz: 34d135125819e0f9c2daf6de081dfe155c5e4b3f
 SHA512:
-  metadata.gz: a6862c1278b9bb0f60b9c64a51e3a680b8f3bf1794c814f9470328c8abc8ee340032534fdbf6f210df1beda103d6a5682fa6f74172172a4eadff1e7a6b659615
-  data.tar.gz: 8c92c6d90d313131c88a21fda089564f0f064d79d5387c07a0ee1f94d1357123c3cfc5f2cf700d2fcb8a5a62e937d1949a7b4eff9f9d43f544dcf89528f9b9aa
+  metadata.gz: 84039fd839735f1c8455f5ad54e43e27e6e90c94a1aea57535fcb4af3fce6906a1ed6ac50833f14e57bb1ac4b1acb3c7afc2056a286a10be233bae935a36bada
+  data.tar.gz: 25092c748a4214a81b0d27ba6f01828e68854599f7a297638a784366679edf495b5a234f5ca5a17c756de90f84338f53f4a6af35efb061da22297a05e02bbb4d

data/README.md

@@ -13,52 +13,114 @@
 
 # pardner
 
-A decorator library for ActiveRecord that has features to fit in nicely with the ActiveModel world
+A decorator library for ActiveRecord that has features to fit in nicely
+with the ActiveModel world
 
 ## Use cases
 
 1. Presenters for views
-2. Handle form params and translate them to what the modal understands
-3. Creating or updating multiple ActiveRecord models atomically
+2. Translate between form params and model attributes
+3. Save multiple ActiveRecord models atomically
 4. Adding optional validations
 5. And more!
 
-## 1. Presenters
+## Usage
 
-A presenter can be used as an alternative to a view helper to add logic
-to a view. In this example we add a `description` method to a decorator
-for the view:
+``` ruby
+# Decorate an ActiveRecord or ActiveModel class by creating a subclass
+# of Pardner::Base. In this example we'll pretend a User active record
+# class exists.
 
-    # app/models/conestoga_wagon.rb
-    class ConestogaWagon < ActiveRecord::Base
-      attr_accessor :wheels_count, :covered
-    end
+class SilverMiner < Pardner::Base
+  howdy_pardner User
+end
 
-    # app/presenters/conestoga_wagon_presenter.rb
-    class ConestogaWagonPresenter < Pardner::Base
-      howdy_pardner ConestogaWagon
+# Instantiate it by calling `.new` and passing in a User object:
+miner = SilverMiner.new User.find(123)
+miner.new_record? # => true
+miner.id          # => 123
 
-      def description
-        covered_string = covered ? "covered" : "uncovered"
-        "a #{wheels_count} wheeled #{covered_string} wagon"
-      end
-    end
+# Behavior can be added to the decorator by defining methods:
+class SilverMiner < Pardner::Base
+  # Add the title 'Silver miner' to the user name
+  def name
+    "Silver miner #{super}"
+  end
+end
+
+miner.name # => 'Silver miner Sam'
+
+# by adding callbacks:
+class SilverMiner < Pardner::Base
+  before_destroy :retirement_party
+
+  private
 
-    # app/view/conestoga_wagons/show.html.haml
-    ...
-    span.description= @conestoga_wagon.description
-    ...
+  def retirement_party
+    years_worked = Time.now.year - self.start_year
+    Cake.create! candles_count: years_worked
+  end
+end
 
-## 2. Handle form params
+miner.destroy # creates a Cake
 
-In this example, the `GoldRush` model has separate `city` and `state`
+# by adding validations:
+class SilverMiner < Pardner::Base
+  validates_inclusion_of :favorite_ore, in: ['silver']
+end
+
+miner.favorite_ore = 'gold'
+miner.valid?     # => false
+```
+
+## More examples
+
+### Presenters
+
+A presenter a way to add logic to a view. It's an alternative to a view
+helper. In this example a ConestogaWagon model is decorated to have a
+`description` method.
+
+```ruby
+# app/models/conestoga_wagon.rb
+# The table has columns is_covered:boolean and wheels_count:integer
+class ConestogaWagon < ActiveRecord::Base
+end
+
+# app/presenters/conestoga_wagon_presenter.rb
+class ConestogaWagonPresenter < Pardner::Base
+  howdy_pardner ConestogaWagon
+
+  def description
+    covered_string = is_covered ? "covered" : "uncovered"
+    "a #{wheels_count} wheeled #{covered_string} wagon"
+  end
+end
+
+# app/controllers/conestoga_wagons_controller.rb
+class ConestogaWagonsController < ApplicationController
+  def show
+    @wagon = ConestogaWagonPresenter.new ConestogaWagon.find(params[:id])
+  end
+end
+```
+
+```haml
+-# app/views/conestoga_wagons/show.html.haml
+span.description= @conestoga_wagon.description
+```
+
+### Translating between form params and model attributes
+
+In this example, the `GoldRush` model has separate `city` and `territory`
 fields, but we want to present that to the user as a single form field.
 The decorator will split the incoming `location` param into `city` and
-`state` fields.
+`territory` fields, and vice versa.
 
+```ruby
     # app/models/gold_rush.rb
+    # The table gold_rushes has columns city:string and territory:string
     class GoldRush < ActiveRecord::Base
-      attr_accessor :city, :state
     end
 
     # app/decorators/gold_rush_form.rb
@@ -66,22 +128,153 @@ The decorator will split the incoming `location` param into `city` and
       howdy_pardner GoldRush
 
       def location
-        "#{city}, #{state}"
+        "#{city}, #{territory}"
       end
 
       def location=(val)
-        self.city, self.state = val.split ','
+        self.city, self.territory = val.split ','
       end
     end
 
     # app/controllers/gold_rushes_controller.rb
-    def new
-      @gold_rush = GoldRushForm.new GoldRush.new
+    class GoldRushesController < ApplicationController
+      def new
+        @gold_rush = GoldRushForm.new GoldRush.new
+      end
+
+      def create
+        @gold_rush = GoldRushForm.new GoldRush.new
+        @gold_rush.attributes = params[:gold_rush]
+
+        if @gold_rush.save
+          flash[:notice] = "There's gold in them thar hills"
+        else
+          render :new
+        end
+      end
     end
+```
 
-    # app/view/gold_rushes/new.html.haml
+```haml
+    -# app/view/gold_rushes/new.html.haml
     = form_for @gold_rush do |form|
       form.text :location
+      form.submit
+```
+
+### Saving multiple ActiveRecord models atomically
+
+A decorator can be a convenient way to coordinate changes to several
+models atomically. Model callbacks can also be used for this but have
+some downsides:
+
+* sometimes its not clear which model should have the callback,
+* decorators can opt-in more easily than callbacks,
+* and extensive use of callbacks can lead to infinite loops.
+
+In this example, when a gold rush is declared a bunch of supporting
+models need to be created.
+
+```ruby
+# app/controllers/gold_rushes_controller.rb
+class GoldRushesController < ApplicationController
+  def create
+    @gold_rush = GoldRushDeclared.new GoldRush.new
+    @gold_rush.attributes = params[:gold_rush]
+
+    if @gold_rush.save
+      flash[:notice] = "There's gold in them thar hills"
+    else
+      render :new
+    end
+  end
+end
+
+# app/services/gold_rush_declared.rb
+class GoldRushDeclared < Pardner::Base
+  howdy_pardner GoldRush
+  before_validate :build_infrastructure
+  validate :mining_town_must_exist
+  validate :transport_must_exist
+
+  private
+
+  def build_infrastructure
+    if MiningTown.where(territory: self.territory).is_nearby(self).empty?
+      MiningTown.create! territory: self.territory, name: "Town near #{self.name}"
+    end
+
+    if Railroad.is_nearby(self).empty? && WagonTrail.is_nearby(self).empty?
+      WagonTrail.create! territory: self.territory, destination: self.location
+    end
+  end
+
+  def mining_town_must_exist
+    return if MiningTown.is_nearby(self)
+    errors.add :base, 'no mining town exists'
+  end
+
+  def transport_must_exist
+    return if Railroad.is_nearby(self) || WagonTrail.is_nearby(self)
+    errors.add :base, 'no transport exists'
+  end
+end
+```
+
+### Adding optional validations
+
+In this example, we have two controllers for the same resource. One
+supports an admin interface and one is customer facing. We want the
+customer facing one to do more validation than the admin one.
+
+```ruby
+# app/decorators/small_posse.rb
+class SmallPosse < Pardner::Base
+  howdy_pardner Posse
+  validate :must_be_small
+
+  MAX_SIZE = 5
+
+  private
+
+  def must_be_small
+    if deputies_count > MAX_SIZE
+      errors.add :deputies, "must be less than #{MAX_SIZE}"
+    end
+  end
+end
+
+# app/controllers/posses_controller.rb
+class PossesController < ApplicationController
+  def create
+    # This controller is customer facing so they can only create small posses
+    @posse = SmallPosse.new Posse.new
+    @posse.attributes = params[:posse]
+
+    if @posse.save
+      flash[:notice] = 'Get a rope'
+    else
+      render :new
+    end
+  end
+end
+
+# app/controllers/admin/posses_controller.rb
+module Admin
+  class PossesController < ApplicationController
+    def create
+      # This controller is for admins so they can do what they want
+      @posse = Posse.new params[:posse]
+
+      if @posse.save
+        flash[:notice] = 'Every day above ground is a good day'
+      else
+        render :new
+      end
+    end
+  end
+end
+```
 
 ## Installation
 
@@ -99,9 +292,11 @@ Or install it yourself as:
 
     $ gem install pardner
 
-## Usage
+## Similar projects
 
-TODO: Write usage instructions here
+* draper https://github.com/drapergem/draper
+* informal https://github.com/joshsusser/informal
+* more https://www.ruby-toolbox.com/categories/rails_presenters
 
 ## Development
 
@@ -111,10 +306,9 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/pardner. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at https://github.com/ajh/pardner.
 
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
-

data/lib/pardner/base.rb

@@ -87,8 +87,11 @@ module Pardner
     def save
       valid? or return false
 
-      status = ActiveRecord::Base.transaction do
-        run_callbacks(:save) { super }
+      status = nil
+
+      ActiveRecord::Base.transaction do
+        status = run_callbacks(:save) { super }
+        status or raise ActiveRecord::Rollback
       end
 
       status == true

data/lib/pardner/version.rb

@@ -1,3 +1,3 @@
 module Pardner
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pardner
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Andy Hartford
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-03-09 00:00:00.000000000 Z
+date: 2016-03-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -252,7 +252,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.4.5
 signing_key: 
 specification_version: 4
 summary: A decorator library for ActiveRecord