draft_punk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e3f046dd681c4ce95232727b80e08571f86a9b3d
+  data.tar.gz: d9d79883283cf851eaf23d62ff7a799b881747b5
+SHA512:
+  metadata.gz: 9f3c56febd0bddc7e51aa5b8977be58cd00609cb22d9d08af7d186f236ee980f22e0850f7a8b198af91d9258fa229c8b2249c96274d526a7aaf5f62617b93d9c
+  data.tar.gz: c3186ea26726487f53d9d061c03ba1c1756ca92d3b5050cc730f2c874b1c98da7f80006b119f0bc6df6c505c7770a0088ddb811d63b50e4c5bbea73074108d4d

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 2.1.2

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,13 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, age, or religion.
+
+Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
+
+This Code of Conduct is adapted from the [Contributor Covenant](http:contributor-covenant.org), version 1.0.0, available at [http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/)

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Steve Hodges
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,238 @@
+# DraftPunk
+
+DraftPunk allows editing of a draft version of an ActiveRecord model and its associations.
+
+When it's time to edit, a draft version is created in the same table as the object. You can specify which associations should also be edited and stored with that draft version. All associations are stored in their native table.
+
+When it's time to publish, any attributes changed on your draft object persist to the original object. All associated objects behave the same way. Any associated have_many objects which are deleted on the draft are deleted on the original object.
+
+## Why this gem compared to similar gems?
+
+I wrote this gem because other draft/publish gems had limitations that ruled them out in my use case. Here's a few reasons I ended up rolling my own:
+
+1. This gem simply works with your existing database (plus one new column on your original object).
+2. I tried using an approach that stores incremental changes in another table. For instance, some draft gems rely on a Versioning gem, or otherwise store incremental changes in the database.
+
+    That gets super complicated, or simply don't work, with associations, nested associations, and/or if you want users to be able to *edit* those changes.
+3. This gem works with Rails `accepts_nested_attributes`. That Rails pattern doesn't work when you pass in objects which aren't associated; for instance, if you try to save a new draft image on your Blog post via nested_attributes, Rails will throw a 404 error. It got nasty, fast, so I needed a solution that worked well with Rails.
+4. I prefer to store drafts in the same table as the original. While this has a downside (see downsides, below), it means:
+    1. Your draft acts like the original. You can execute all the same methods on it, reuse presenters, forms, form_objects, decorators, or anything else. It doesn't just quack like a duck, it **is** a duck.
+
+    2. This prevents your table structure from getting out of sync. If you're using DraftPunk, when you add a new attribute to your model, or change a column, both your live/approved version and your draft version are affected. Using a different pattern, if they live in separate tables, you may need to run migrations on both tables (or, migrate the internals of a version diff if your draft gem relies on something like Paper Trail or VestalVersion)
+  
+
+### Downsides
+
+Since DraftPunk saves in the same table as the original, your queries in those tables will return both approved and draft objects. In other words, without modifying your Rails app further, your BusinessController index action (in a typical rails app) will return drafts and approved objects. DraftPunk adds scopes to help you manage this. See the "What about the rest of the application? People are seeing draft businesses!" section below for two patterns to address this. 
+
+## Usage
+
+### Getting Started
+To enable drafts for a model, first add an approved_version_id column (Integer), which will be used to track its draft.
+
+Simply call requires_approval in your model to enable DraftPunk on that model and its associations:
+
+    class Business << ActiveRecord::Base
+      has_many :employees
+      has_many :images
+      has_one  :address
+      has_many :vending_machines
+
+      requires_approval 
+    end
+
+DraftPunk will generate drafts for all associations, by default. So when you create a draft Business, that draft will also have draft `employees`, `vending_machines`, `images`, and an `address`. The whole tree is recursively duplicated.
+
+**Do not call `requires_approval` on Business's associated objects.** The behavior automatically cascades down til there are no more associations.
+
+### Customize which associations have drafts created
+
+Optionally, you can tell DraftPunk which associations the user will edit - the associations which should have a draft created.
+
+If you only want the :address association to have a draft created, add a CREATES_NESTED_DRAFTS_FOR constant in your model:
+
+    CREATES_NESTED_DRAFTS_FOR = [:address] # When creating a business's draft, only :address will have drafts created
+
+To disable drafts for all assocations for this model, simply pass an empty array:
+
+    CREATES_NESTED_DRAFTS_FOR = [] # When creating a business's draft, no associations will have drafts created
+
+**WARNING: If you are setting associations via accepts_nested_attributes** _all changes to the draft, including associations, get set on the
+draft object (as expected). If your form includes associated objects which weren't defined in requires_approval, your save will fail since
+the draft object doesn't HAVE those associations to update! In this case, you should probably add that association to the
+`associations` param when you call `requires_approval`._
+
+
+### Working with a draft
+
+So you have an ActiveRecord object:
+
+    @business = Business.first
+
+And you want it's editable version - its draft:
+
+    @my_draft = @business.editable_version   #If @business doesn't have a draft yet, it creates one for you. 
+
+Now you can edit the draft. Perhaps in your controller, you have:
+
+    def edit
+      @my_draft = @business.editable_version
+      render 'form'
+    end
+
+In the view (or even in rails console), you'll want to be editing that draft version. For instance, pass your draft into the business's form, and it'll just work!
+
+    form_for @my_draft
+
+And, voila, the user is editing the draft.
+
+Your update action might look like so:
+
+    def update
+      @my_draft = Business.find(params[:id])
+      .... do some stuff here
+    end
+
+So your draft is automagically getting updated.
+
+Say your `@business` has a `name` attribute:
+
+    @business.name
+    => "DraftPunk LLC"
+
+Ok, you just incorperated so your name changed.
+
+    @my_draft = @business.editable_version
+    @my_draft.name = "DraftPunk Incorperated"
+    @my_draft.save
+
+At this point, that change is only saved on the draft version of your business. The original business still has the name DraftPunk LLC.
+
+#### Publish the draft - aka making your changes live
+
+So you want to make your changes live:
+
+    @business.name
+    => "DraftPunk LLC"
+    @business.draft.name
+    => "DraftPunk Incorperated"    
+    @business.publish_draft!
+    @business.name
+    => "DraftPunk Incorperated"    
+
+**All of the @business associations copied from the draft**. More correctly, the foreign_keys on has_many associations are changed, set to the original object (@business) id. All the old associations (specified in requires_approval) on @business are destroyed.
+
+At this point, the draft is destroyed. Next time you call `editable_version`, a draft will be created for you.
+
+### Tracking drafts
+Your original model has a few methods available:
+
+    @business.id
+    => 1    
+    @draft = @business.draft
+    => Business(id: 2, ...)
+    @draft.approved_version
+    => Business(id: 1, ...)
+    @draft.is_draft?
+    => true
+    @draft.has_draft?
+    => false
+    @business.is_draft?
+    => false
+    @business.has_draft?
+    => true
+
+Your associations can have this behavior, too, which could be useful in your application. If you want your draft associations to track their live version, add an `approved_version_id` column (Integer) to each table. You'll have all the methods demonstrated above. This also allows you to access a child association directly, ie. 
+
+    @live_image = @business.images.first
+    => Image(id: 1, ...)
+    @draft_image = @business.draft.images.first
+    => Image(id: 2, ...)
+
+At this point, if you don't have `approved_version_id` on the `images` table, there's no way for you to know that @draft_image was originally a copy of @live_image. If you have approved_version_id on your table, you can call:
+
+    @draft_image.approved_version
+    => Image(id: 1, ...)
+    @live_image.draft
+    => Image(id: 2, ...)
+
+You now know for certain that the two are associated, which could be useful in your app.
+
+### Free ActiveRecord scopes
+All models which have `approved_version_id` also have these scopes: `approved` and `draft`.
+
+## What about the rest of the application? People are seeing draft businesses!
+
+You can implement this in a variety of ways. Here's two approaches:
+
+#### Set a Rails `default_scope` on your model.
+
+This is the quickest, most DRY way to address this, but of course default_scopes aren't always the right answer for every Rails app.
+
+    default_scope Business.approved
+
+Then, any ActiveRecord queries for Business will be scoped to only approved models. Your `draft` scope, and `draft` association will ignore this scope, so @business.draft and Business.draft will both continue to return draft objects. 
+
+
+#### Or, modify your controllers to use the `approved` scope
+Alternately, you may want to modify your controllers to only access _approved_ objects. For instance, your business controller should use that `approved` scope when it looks up businesses. i.e.
+
+    class BusinessesController < ApplicationController
+      def index
+        @businesses = Business.approved.all
+        ... more code
+      end
+    end
+
+## TODO: Customizing Association associations (grandchildren) using accepts_nested_drafts_for
+
+## TODO: Customizing approvable_attributes, changes_require_approval
+
+## Options before creating a draft
+
+When calling `requires_approval`, you can pass a `nullify` option to set attributes to null once the draft is created:
+
+    requires_approval nullify: [:subdomain]
+
+This could be useful if your model has an attribute which should not persist. In this example, each Business has a unique subdomain (ie. business_name.foo.com ). By nullifying this out, the subdomain on the draft would be nil. 
+
+### Before create callback
+
+If you define a method on your model called `before_create_draft`, that method will be executed before the draft is created.
+
+You can access `self` (which is the DRAFT version being created), or the `temporary_approved_object` (the original object) in this method
+
+    def before_create_draft
+      logger.warn "#{self.name} is being created from #{temporary_approved_object.class.name} ##{temporary_approved_object.id}" # outputs: DerpCorp is being created from Business #1
+    end
+
+## Options before publishing a draft
+
+### Before publish draft method
+
+If you define a method on your model called `before_publish_draft`, that method will be executed before the draft is published. Specifically, it happens after all attributes are copied from the draft to the approved version, and right before the approved version is saved. This allows you to do whatever you'd like to the model before it is saved.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'draft_punk'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install draft_punk
+
+## Contributing
+
+1. Fork it ( https://github.com/stevehodges/draft_punk/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Be consistent with the rest of this repo. Write thorough tests (rspec) and documentation (yard)
+4. Commit your changes (`git commit -am 'Add some feature'`)
+5. Push to the branch (`git push origin my-new-feature`)
+6. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,4 @@
+require "rubygems"
+require "bundler/setup"
+require "bundler/gem_tasks"
+require 'rake/testtask'

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "draft_punk"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/draft_punk.gemspec

@@ -0,0 +1,45 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'draft_punk/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "draft_punk"
+  spec.version       = DraftPunk::VERSION
+  spec.authors       = ["Steve Hodges"]
+  spec.email         = ["steve.hodges@localstake.com"]
+
+  spec.summary       = %q{Easy editing of a draft version of an ActiveRecord model and its associations, and publishing said draft's changes back to the original models.}
+  spec.description   = <<-EOF
+DraftPunk allows editing of a draft version of an ActiveRecord model and its associations.
+
+When it's time to edit, a draft version is created in the same table as the object. You can specify which associations should also be edited and stored with that draft version. All associations are stored in their native table.
+
+When it's time to publish, any attributes changed on your draft object persist to the original object. All associated objects behave the same way. Any associated have_many objects which are deleted on the draft are deleted on the original object.
+
+This gem doesn't rely on a versioning gem and doesn't store incremental diffs of the model. It simply works with your existing database (plus one new column on your original object).
+EOF
+  spec.homepage      = "https://github.com/stevehodges/draftpunk"
+  spec.license       = "MIT"
+  spec.has_rdoc      = 'yard'
+
+
+  spec.required_ruby_version  = ">= 2.0.0"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency     "amoeba",    "~> 3.0"
+  spec.add_runtime_dependency     "unscoped_associations", "< 1.0"
+  spec.add_runtime_dependency     "differ",    "< 0.2"
+  spec.add_runtime_dependency     'rails',     "~> 3.0"
+
+  spec.add_development_dependency "bundler",   "~> 1.9"
+  spec.add_development_dependency "rake",      "~> 10.0"
+  spec.add_development_dependency "rspec",     "~> 2.0"
+  spec.add_development_dependency "sqlite3",   "~> 1.0"
+  spec.add_development_dependency "yard",      "< 1.0"
+
+end

data/lib/activerecord_class_methods.rb

@@ -0,0 +1,179 @@
+require 'activerecord_instance_methods'
+require 'draft_diff_instance_methods'
+
+module DraftPunk
+  module Model
+    module ActiveRecordClassMethods
+      # Call this method in your model to setup approval. It will recursively apply to its associations,
+      # thus does not need to be explicity called on its associated models (and will error if you try).
+      #
+      # This model must have an approved_version_id column (Integer), which will be used to track its draft
+      # 
+      # For instance, your Business model:
+      #  class Business << ActiveRecord::Base
+      #    has_many :employees
+      #    has_many :images
+      #    has_one  :address
+      #    has_many :vending_machines
+      #
+      #    requires_approval # When creating a business's draft, :employees, :vending_machines, :images, and :address will all have drafts created
+      #  end
+      #
+      # Optionally, specify which associations which the user will edit - associations which should have a draft created
+      # by defining a CREATES_NESTED_DRAFTS_FOR constant for this model.
+      #  
+      #  CREATES_NESTED_DRAFTS_FOR = [:address] # When creating a business's draft, only :address will have drafts created
+      #
+      # To disable drafts for all assocations for this model, simply pass an empty array:
+      # by defining a CREATES_NESTED_DRAFTS_FOR constant for this model.
+      #  CREATES_NESTED_DRAFTS_FOR = [] # When creating a business's draft, no associations will have drafts created
+      #
+      # WARNING: If you are setting associations via accepts_nested_attributes all changes to the draft, including associations, get set on the
+      # draft object (as expected). If your form includes associated objects which weren't defined in requires_approval, your save will fail since
+      # the draft object doesn't HAVE those associations to update! In this case, you should probably add that association to the
+      # +associations+ param here.
+      #
+      # If you want your draft associations to track their live version, add an :approved_version_id column
+      # to each association's table. You'll be able to access that associated object's live version, just
+      # like you can with the original model which called requires_approval. 
+      #
+      # @param nullify [Array] A list of attributes on this model to set to null on the draft when it is created. For
+      #    instance, the _id_ and _created_at_ columns are nullified by default, since you don't want Rails to try to
+      #    persist those on the draft.
+      # @param set_default_scope [Boolean] If true, set a default scope on this model for the approved scope; only approved objects
+      #    will be returned in ActiveRecord queries, unless you call Model.unscoped
+      # @param associations [Array] Use internally; set associations to create drafts for in the CREATES_NESTED_DRAFTS_FOR constant
+      # @return true
+      def requires_approval(associations: [], nullify: [], set_default_scope: false)
+        return unless ActiveRecord::Base.connection.table_exists?(table_name) # Short circuits if you're migrating
+
+        associations = draft_target_associations if associations.empty?
+        set_valid_associations(associations)
+
+        raise DraftPunk::ConfigurationError, "Cannot call requires_approval multiple times for #{name}" if const_defined? :DRAFT_PUNK_IS_SETUP
+        self.const_set :DRAFT_NULLIFY_ATTRIBUTES, [nullify].flatten
+
+        amoeba do
+          nullify nullify
+          # Note that the amoeba associations and customize options are being set in setup_associations_and_scopes_for
+        end
+        setup_amoeba_for self, set_default_scope: set_default_scope
+        true
+      end
+
+      # This will generally be only used in testing scenarios, in cases when requires_approval need to be
+      # called multiple times. Only the usage for that use case is supported. Use at your own risk for other
+      # use cases.
+      def disable_approval!
+        send(:remove_const, :DRAFT_PUNK_IS_SETUP) if const_defined? :DRAFT_PUNK_IS_SETUP
+        send(:remove_const, :DRAFT_NULLIFY_ATTRIBUTES) if const_defined? :DRAFT_NULLIFY_ATTRIBUTES
+        fresh_amoeba do
+          disable
+        end
+      end
+
+      # List of association names this model is configured to have drafts for
+      # @return [Array]
+      def draft_target_associations
+        targets = if const_defined?(:CREATES_NESTED_DRAFTS_FOR) && const_get(:CREATES_NESTED_DRAFTS_FOR).is_a?(Array)
+          const_get(:CREATES_NESTED_DRAFTS_FOR).compact
+        else
+          default_draft_target_associations
+        end.map(&:to_sym)
+      end
+
+      # Whether this model is configured to track the approved version of a draft object.
+      # This will be true if the model has an approved_version_id column
+      #
+      # @return (Boolean)
+      def tracks_approved_version?
+        column_names.include? 'approved_version_id'
+      end
+
+    protected #################################################################
+
+      def default_draft_target_associations
+        reflect_on_all_associations.select do |reflection|
+          is_relevant_association_type?(reflection) &&
+          !reflection.name.in?(%i(draft approved_version)) &&
+          reflection.class_name != name # Self referential associations!!! Don't do them!
+        end.map{|r| r.name.downcase.to_sym }
+      end
+
+      # Rejects the associations if the table hasn't been defined yet. This happens when
+      # running migrations which add that association's table.
+      def set_valid_associations(associations)
+        return const_get(:DRAFT_VALID_ASSOCIATIONS) if const_defined?(:DRAFT_VALID_ASSOCIATIONS)
+        associations = associations.map(&:to_sym)
+        valid_assocations = associations.select do |assoc|
+          reflection = reflect_on_association(assoc)
+          if reflection
+            table_name = reflection.klass.table_name
+            ActiveRecord::Base.connection.table_exists?(table_name)
+          else
+            false
+          end
+        end
+        self.const_set :DRAFT_VALID_ASSOCIATIONS, valid_assocations
+        valid_assocations
+      end
+
+    private ###################################################################
+
+      def setup_amoeba_for(target_class, set_default_scope: false)
+        return if target_class.const_defined?(:DRAFT_PUNK_IS_SETUP)
+        associations = target_class.draft_target_associations
+        associations = target_class.set_valid_associations(associations)
+        target_class.amoeba do
+          enable
+          include_association target_class.const_get(:DRAFT_VALID_ASSOCIATIONS)
+          customize(lambda {|live_obj, draft_obj|
+            draft_obj.approved_version_id = live_obj.id if draft_obj.respond_to?(:approved_version_id)
+            draft_obj.temporary_approved_object = live_obj
+          })
+        end
+        target_class.const_set :DRAFT_PUNK_IS_SETUP, true
+
+        setup_associations_and_scopes_for target_class, set_default_scope: set_default_scope
+        setup_draft_association_persistance_for_children_of target_class, associations
+      end
+
+      def setup_draft_association_persistance_for_children_of(target_class, associations=nil)
+        associations = target_class.draft_target_associations unless associations
+        target_reflections = associations.map do |assoc|
+          reflection = target_class.reflect_on_association(assoc.to_sym)
+          reflection.presence || (raise DraftPunk::ConfigurationError, "#{name} includes invalid association (#{assoc})")
+        end
+        target_reflections.select{|r| is_relevant_association_type?(r) }.each do |assoc|
+          setup_amoeba_for assoc.klass
+        end
+      end
+
+      def setup_associations_and_scopes_for(target_class, set_default_scope: false)
+        target_class.send       :include, InstanceInterrogators unless target_class.method_defined?(:has_draft?)
+        target_class.send       :attr_accessor, :temporary_approved_object
+        target_class.send       :before_create, :before_create_draft if target_class.method_defined?(:before_create_draft)
+
+        return if target_class.reflect_on_association(:approved_version) || !target_class.column_names.include?('approved_version_id')
+        target_class.send       :include, ActiveRecordInstanceMethods
+        target_class.send       :include, DraftDiffInstanceMethods
+        target_class.belongs_to :approved_version, class_name: target_class.name
+        target_class.has_one    :draft, class_name: target_class.name, foreign_key: :approved_version_id, unscoped: true
+        target_class.scope      :approved, -> { where("#{target_class.quoted_table_name}.approved_version_id IS NULL") }
+        if set_default_scope
+          target_class.default_scope target_class.approved
+        else
+          # TODO: fix - the unscoped isn't working with default scope, so not defining this draft scope if set_default_scope
+          target_class.scope      :draft,    -> { unscoped.where("#{target_class.quoted_table_name}.approved_version_id IS NOT NULL") }
+        end
+      end
+
+      def is_relevant_association_type?(activerecord_reflection)
+        # Note when implementing for Rails 4, macro is renamed to something else
+        activerecord_reflection.macro.in? Amoeba::Config::DEFAULTS[:known_macros]
+      end
+
+    end
+
+  end
+end

data/lib/activerecord_instance_methods.rb

@@ -0,0 +1,169 @@
+module DraftPunk
+  module Model
+    module ActiveRecordInstanceMethods
+      #############################
+      # BEGIN CONFIGURABLE METHODS
+      # You can overwrite these methods in your model for custom behavior
+      #############################
+
+      # Determines whether to edit a draft, or the original object. This only controls
+      # the object returned by editable version, and draft publishing. If changes to not
+      # require approval, publishing of the draft is short circuited and will do nothing.
+      #
+      # Overwrite in your model to implement logic for whether to use a draft.
+      #
+      # @return [Boolean]
+      def changes_require_approval?
+        true # By default, all changes require approval
+      end
+
+      # Which attributes of this model are published from the draft to the approved object. Overwrite in model
+      # if you don't want all attributes of the draft to be saved on the live object.
+      #
+      # This is an array of attributes (including has_one association id columns) which will be saved 
+      # on the object when its' draft is approved.
+      #
+      # For instance, if you want to omit updated_at, for whatever reason, you would define this in your model:
+      #
+      #  def approvable_attributes
+      #    self.attributes.keys - ["created_at", "updated_at"]
+      #  end
+      #
+      # WARNING: Don't include "created_at" if you don't want to modify this object's created_at!
+      #
+      # @return [Array] names of approvable attributes
+      def approvable_attributes
+        self.attributes.keys - ["created_at"]
+      end
+      #############################
+      # END CONFIGURABLE METHODS
+      #############################
+
+
+      # Updates the approved version with any changes on the draft, and all the drafts' associated objects.
+      # 
+      # If the approved version changes_require_approval? returns false, this method exits early and does nothing
+      # to the approved version.
+      #
+      # THE DRAFT VERSION IS DESTROYED IN THIS PROCESS. To generate a new draft, simply call <tt>editable_version</tt>
+      # again on the approved object.
+      # 
+      # @return [ActiveRecord Object] updated version of the approved object
+      def publish_draft!
+        @live_version  = get_approved_version
+        @draft_version = editable_version
+        return unless changes_require_approval? && @draft_version.is_draft? # No-op. ie. the business is in a state that doesn't require approval.
+
+        transaction do
+          save_attribute_changes_and_belongs_to_assocations_from_draft
+          update_has_many_and_has_one_associations_from_draft
+          @live_version.draft.destroy # We have to do this since we moved all the draft's has_many associations to @live_version. If you call "editable_version" later, it'll build the draft.
+        end
+        @live_version = self.class.find(@live_version.id)
+      end
+
+      # Get the object's draft if changes require approval; this method creates one if it doesn't exist yet
+      # If changes do not require approval, the original approved object is returned
+      #
+      # @return ActiveRecord Object
+      def editable_version
+        return get_approved_version unless changes_require_approval?
+        is_draft? ? self : get_draft
+      end
+
+      # Get the approved version. Intended for use on a draft object, but works on a live/approved object too
+      #
+      # @return (ActiveRecord Object)
+      def get_approved_version
+        approved_version || self
+      end
+
+    protected #################################################################
+
+      def get_draft
+        draft || create_draft_version
+      end
+
+    private ####################################################################
+
+      def create_draft_version
+        # Don't call this directly. Use editable_version instead.
+        return draft if draft.present?
+        dupe = amoeba_dup
+        begin
+          dupe.approved_version = self
+          dupe.save!
+        rescue => message
+          raise DraftCreationError, message
+        end
+        draft
+      end
+
+      def save_attribute_changes_and_belongs_to_assocations_from_draft
+        @draft_version.attributes.each do |attribute, value|
+          next unless attribute.in? usable_approvable_attributes
+          @live_version.send("#{attribute}=", value)
+        end
+        @live_version.before_publish_draft if @live_version.respond_to?(:before_publish_draft)
+        @live_version.save!
+      end
+
+      def update_has_many_and_has_one_associations_from_draft
+        self.class.draft_target_associations.each do |assoc|
+          reflection = self.class.reflect_on_association(assoc)
+
+          reflection_is_has_many(reflection) ? @live_version.send(assoc).destroy_all : @live_version.send(assoc).destroy
+
+          attribute_updates = {}
+          attribute_updates[reflection.foreign_key] = @live_version.id
+          attribute_updates['updated_at']           = Time.now if reflection.klass.column_names.include?('updated_at')
+          attribute_updates['approved_version_id']  = nil if reflection.klass.tracks_approved_version?
+
+          reflection_is_has_many(reflection) ? @draft_version.send(assoc).update_all(attribute_updates) : @draft_version.send(assoc).update_attributes(attribute_updates, without_protection: true)
+        end
+      end
+
+      def usable_approvable_attributes
+        nullified_attributes = self.class.const_defined?(:DRAFT_NULLIFY_ATTRIBUTES) ? self.class.const_get(:DRAFT_NULLIFY_ATTRIBUTES) : []
+        approvable_attributes.map(&:to_s) - nullified_attributes.map(&:to_s) - ['approved_version_id', 'id']
+      end
+
+      def current_approvable_attributes
+        attribs = {}
+        attributes.each do |k,v|
+          attribs[k] = v if k.in?(diff_relevant_attributes)
+        end
+      end
+
+      def association_tracks_approved_version?(name)
+        self.class.reflect_on_association(name.to_sym).klass.column_names.include? 'approved_version_id'
+      end
+
+      def association_is_has_many(name)
+        # Note when implementing for Rails 4, macro is renamed to something else
+        self.class.reflect_on_association(name.to_sym).macro == :has_many
+      end
+
+      def reflection_is_has_many(reflection)
+        # Note when implementing for Rails 4, macro is renamed to something else
+        reflection.macro == :has_many
+      end
+
+    end
+
+    module InstanceInterrogators
+      # @return [Boolean] whether the current ActiveRecord object is a draft
+      def is_draft?
+        raise DraftPunk::ApprovedVersionIdError unless respond_to?("approved_version_id")
+        approved_version_id.present?
+      end
+
+      # @return [Boolean] whether the current ActiveRecord object has a draft version
+      def has_draft?
+        raise DraftPunk::ApprovedVersionIdError unless respond_to?(:approved_version_id)
+        draft.present?
+      end
+    end
+
+  end
+end

data/lib/draft_diff_instance_methods.rb

@@ -0,0 +1,86 @@
+module DraftPunk
+  module Model
+    module DraftDiffInstanceMethods
+      require 'differ'
+      # Return the differences between the live and draft object.
+      #
+      # If include_associations is true, it will return the diff for all child associations, recursively until it gets
+      # to the bottom of your draft tree. This only works for associations which have the approved_version_id column
+      #
+      # @param include_associations [Boolean] include diff for child objects, recursive (possibly down to grandchildren and beyond)
+      # @param include_all_attributes [Boolean] return all attributes in the results, including those which have not changed
+      # @param include_diff [Boolean] include an html formatted diff of changes between the live and draft, for each attribute 
+      # @param diff_format [Symbol] format the diff output per the options available in differ (:html, :ascii, :color)
+      # @return (Hash)
+      def draft_diff(include_associations: false, parent_object_fk: nil, include_all_attributes: false, include_diff: false, diff_format: :html, recursed: false)
+        draft_obj = recursed ? draft : get_draft # get_draft will create missing drafts. Based on the logic, this should only happen when you *first* call draft_diff
+        get_object_changes(self, draft_obj, include_associations, parent_object_fk, include_all_attributes, include_diff, diff_format)
+      end
+
+    protected #################################################################
+      def current_approvable_attributes
+        attribs = {}
+        attributes.each do |k,v|
+          attribs[k] = v if k.in?(diff_relevant_attributes)
+        end
+      end    
+
+    private ####################################################################
+
+      def get_object_changes(approved_obj, draft_obj, include_associations, parent_object_fk, include_all_attributes, include_diff, diff_format)
+        diff = {}
+        approved_attribs = approved_obj ? approved_obj.current_approvable_attributes : {}
+        draft_attribs    = draft_obj    ? draft_obj.current_approvable_attributes    : {}
+        diff_relevant_attributes(parent_object_fk).each do |attrib|
+          live  = approved_attribs[attrib]
+          draft = draft_attribs[attrib]
+          if include_all_attributes || live != draft 
+            diff[attrib] = {live: live, draft: draft}
+            diff[attrib].merge!({diff: Differ.diff_by_word(draft, live).format_as(diff_format)}) if include_diff && (live.present? && draft.present? && live.is_a?(String) && draft.is_a?(String))
+          end
+        end
+        diff.merge!(draft_status: :deleted) if parent_object_fk.present? && draft_attribs[parent_object_fk].nil?
+        diff.merge!(associations_diff(include_all_attributes, include_diff, diff_format)) if include_associations
+        diff[:draft_status] = diff_status(diff, parent_object_fk) unless diff.has_key?(:draft_status)
+        diff[:class_info]   = {table_name: approved_obj.class.table_name, class_name: approved_obj.class.name}
+        diff
+      end
+
+      def associations_diff(include_all_attributes, include_diff, diff_format)
+        diff = {}
+        self.class.draft_target_associations.each do |assoc|
+          next unless association_tracks_approved_version?(assoc)
+          diff[assoc] = []
+          draft_versions = draft.present? ? [draft.send(assoc)].flatten.compact : []
+          approved_versions = [get_approved_version.send(assoc)].flatten.compact
+          foreign_key = self.class.reflect_on_association(assoc).foreign_key
+
+          approved_versions.each do |approved|
+            obj_diff = approved.draft_diff(include_associations: true, parent_object_fk: foreign_key, include_all_attributes: include_all_attributes, include_diff: include_diff, diff_format: diff_format, recursed: true)
+            obj_diff.merge(draft_status: :deleted) unless draft_versions.find{|obj| obj.approved_version_id == approved.id }
+            diff[assoc] << obj_diff if (include_all_attributes || obj_diff[:draft_status] != :unchanged)
+          end
+          draft_versions.select{|obj| obj.approved_version_id.nil? }.each do |draft|
+            diff[assoc] << draft.draft_diff(include_associations: true, include_all_attributes: include_all_attributes, recursed: true).merge(draft_status: :added)
+          end
+        end
+        diff.select{|k,v| v.present? || include_all_attributes}
+      end
+
+      def diff_status(diff, parent_object_fk)
+        return if diff.has_key?(:status)
+        diff.each do |attrib, value|
+          if value.is_a?(Hash) && !attrib.in?([parent_object_fk.to_s, 'id'])
+            return :changed unless value[:live] == value[:draft]
+          end
+        end
+        :unchanged
+      end
+
+      def diff_relevant_attributes(parent_object_fk=nil)
+        (usable_approvable_attributes + ['id'] - ['updated_at', 'approved_version_id', parent_object_fk]).map(&:to_s).uniq.compact
+      end
+
+    end
+  end
+end

data/lib/draft_punk.rb

@@ -0,0 +1,46 @@
+require 'draft_punk/version'
+require 'amoeba'
+require 'unscoped_associations'
+require 'activerecord_class_methods'
+require 'helper_methods'
+
+module DraftPunk
+  module Model
+    def self.included(base)
+      base.send :extend, ActiveRecordClassMethods
+    end
+  end
+
+  class ConfigurationError < RuntimeError
+    def initialize(message)
+    	@caller = caller[0]
+      @message = message
+    end
+    def to_s
+      "#{@caller} error: #{@message}"
+    end
+  end
+
+  class ApprovedVersionIdError < ArgumentError
+    def initialize(message=nil)
+      @message = message
+    end
+    def to_s
+    	"this model doesn't have an approved_version_id column, so you cannot access its draft or approved versions. Add a column approved_version_id (Integer) to enable this tracking."
+    end
+  end
+
+  class DraftCreationError < ActiveRecord::RecordInvalid
+    def initialize(message)
+      @message = message
+    end
+    def to_s
+      "the draft failed to be created: #{@message}"
+    end
+  end
+
+end
+
+ActiveSupport.on_load(:active_record) do
+  include DraftPunk::Model
+end

data/lib/draft_punk/version.rb

@@ -0,0 +1,3 @@
+module DraftPunk
+  VERSION = "0.1.0"
+end

data/lib/helper_methods.rb

@@ -0,0 +1,33 @@
+module DraftPunkHelper
+  def summarize_draft_changes(draft_diff)
+    changed = []
+    draft_diff.except("id", :draft_status, :class_info).each do |k,v|
+      if v.is_a?(Array)
+        changed << summarize_association_changes(k,v)
+      else
+        changed << k
+      end
+    end
+    return "Changed: #{changed.compact.to_sentence}" if changed.present?
+  end
+
+  def summarize_association_changes(assoc, values)
+    return assoc if did_association_change?(values)
+  end
+
+  def did_association_change?(children)
+    return true if children.is_a?(Hash) && children[:diff_status] !=:unchanged
+    children.each do |obj|
+      obj.each do |k,v|
+        if v.is_a?(Array) #nested association
+          return true if did_association_change?(v)
+        elsif k == :draft_status
+          return true if v != :unchanged
+        end
+      end
+    end
+    false
+  end
+end
+
+ActionView::Base.send :include, DraftPunkHelper

metadata

@@ -0,0 +1,196 @@
+--- !ruby/object:Gem::Specification
+name: draft_punk
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Steve Hodges
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-01-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: amoeba
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: unscoped_associations
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: differ
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: |
+  DraftPunk allows editing of a draft version of an ActiveRecord model and its associations.
+
+  When it's time to edit, a draft version is created in the same table as the object. You can specify which associations should also be edited and stored with that draft version. All associations are stored in their native table.
+
+  When it's time to publish, any attributes changed on your draft object persist to the original object. All associated objects behave the same way. Any associated have_many objects which are deleted on the draft are deleted on the original object.
+
+  This gem doesn't rely on a versioning gem and doesn't store incremental diffs of the model. It simply works with your existing database (plus one new column on your original object).
+email:
+- steve.hodges@localstake.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- draft_punk.gemspec
+- lib/activerecord_class_methods.rb
+- lib/activerecord_instance_methods.rb
+- lib/draft_diff_instance_methods.rb
+- lib/draft_punk.rb
+- lib/draft_punk/version.rb
+- lib/helper_methods.rb
+homepage: https://github.com/stevehodges/draftpunk
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Easy editing of a draft version of an ActiveRecord model and its associations,
+  and publishing said draft's changes back to the original models.
+test_files: []
+has_rdoc: yard