draftsman 0.1.0

data/lib/draftsman/model.rb

@@ -0,0 +1,428 @@
+module Draftsman
+  module Model
+
+    def self.included(base)
+      base.send :extend, ClassMethods
+    end
+
+    module ClassMethods
+      # Declare this in your model to enable the Draftsman API for it. A draft of the model is available in the `draft`
+      # association (if one exists).
+      #
+      # Options:
+      #
+      # :class_name
+      # The name of a custom `Draft` class. This class should inherit from `Draftsman::Draft`. A global default can be
+      # set for this using `Draftsman.draft_class_name=` if the default of `Draftsman::Draft` needs to be overridden.
+      #
+      # :ignore
+      # An array of attributes for which an update to a `Draft` will not be stored if they are the only ones changed.
+      #
+      # :only
+      # Inverse of `ignore` - a new `Draft` will be created only for these attributes if supplied. It's recommended that
+      # you only specify optional attributes for this (that can be empty).
+      #
+      # :skip
+      # Fields to ignore completely.  As with `ignore`, updates to these fields will not create a new `Draft`. In
+      # addition, these fields will not be included in the serialized versions of the object whenever a new `Draft` is
+      # created.
+      #
+      # :meta
+      # A hash of extra data to store.  You must add a column to the `drafts` table for each key. Values are objects or
+      # `procs` (which are called with `self`, i.e. the model with the `has_drafts`). See
+      # `Draftsman::Controller.info_for_draftsman` for an example of how to store data from the controller.
+      #
+      # :draft
+      # The name to use for the `draft` association shortcut method. Default is `:draft`.
+      #
+      # :published_at
+      # The name to use for the method which returns the published timestamp. Default is `published_at`.
+      #
+      # :trashed_at
+      # The name to use for the method which returns the soft delete timestamp. Default is `trashed_at`.
+      def has_drafts(options = {})
+        # Lazily include the instance methods so we don't clutter up
+        # any more ActiveRecord models than we need to.
+        send :include, InstanceMethods
+
+        class_attribute :draftsman_options
+        self.draftsman_options = options.dup
+
+        class_attribute :draft_association_name
+        self.draft_association_name = options[:draft] || :draft
+
+        class_attribute :draft_class_name
+        self.draft_class_name = options[:class_name] || Draftsman.draft_class_name
+
+        [:ignore, :skip, :only].each do |key|
+          draftsman_options[key] = ([draftsman_options[key]].flatten.compact || []).map(&:to_s)
+        end
+
+        draftsman_options[:ignore] << "#{self.draft_association_name}_id"
+
+        draftsman_options[:meta] ||= {}
+
+        attr_accessor :draftsman_event
+
+        class_attribute :published_at_attribute_name
+        self.published_at_attribute_name = options[:published_at] || :published_at
+
+        class_attribute :trashed_at_attribute_name
+        self.trashed_at_attribute_name = options[:trashed_at] || :trashed_at
+
+        # `belongs_to :draft` association
+        belongs_to self.draft_association_name, :class_name => self.draft_class_name, :dependent => :destroy
+
+        # Scopes
+        scope :drafted,   lambda { where("#{self.draft_association_name}_id IS NOT NULL") }
+        scope :published, lambda { where("#{self.published_at_attribute_name} IS NOT NULL") }
+        scope :trashed,   lambda { where("#{self.trashed_at_attribute_name} IS NOT NULL") }
+        scope :live,      lambda { where("#{self.trashed_at_attribute_name} IS NULL") }
+      end
+
+      # Returns whether or not `has_drafts` has been called on this model.
+      def draftable?
+        method_defined?(:draftsman_options)
+      end
+
+      # Serializes attribute changes for `Draft#object_changes` attribute.
+      def serialize_draft_attribute_changes(changes)
+        serialized_attributes.each do |key, coder|
+          if changes.key?(key)
+            coder = Draftsman::Serializers::Yaml unless coder.respond_to?(:dump) # Fall back to YAML if `coder` has no `dump` method
+            old_value, new_value = changes[key]
+            changes[key] = [coder.dump(old_value), coder.dump(new_value)]
+          end
+        end
+      end
+
+      # Used for `Draft#object` attribute
+      def serialize_attributes_for_draftsman(attributes)
+        serialized_attributes.each do |key, coder|
+          if attributes.key?(key)
+            coder = Draftsman::Serializers::Yaml unless coder.respond_to?(:dump) # Fall back to YAML if `coder` has no `dump` method
+            attributes[key] = coder.dump(attributes[key])
+          end
+        end
+      end
+
+      # Returns whether or not a `trashed_at` timestamp is set up on this model.
+      def trashable?
+        draftable? && method_defined?(self.trashed_at_attribute_name)
+      end
+
+      # Unserializes attribute changes for `Draft#object_changes` attribute.
+      def unserialize_draft_attribute_changes(changes)
+        serialized_attributes.each do |key, coder|
+          if changes.key?(key)
+            coder = Draftsman::Serializers::Yaml unless coder.respond_to?(:dump)
+            old_value, new_value = changes[key]
+            changes[key] = [coder.load(old_value), coder.load(new_value)]
+          end
+        end
+      end
+
+      # Used for `Draft#object` attribute
+      def unserialize_attributes_for_draftsman(attributes)
+        serialized_attributes.each do |key, coder|
+          if attributes.key?(key)
+            coder = Draftsman::Serializers::Yaml unless coder.respond_to?(:dump)
+            attributes[key] = coder.load(attributes[key])
+          end
+        end
+      end
+    end
+
+    module InstanceMethods
+      # Returns whether or not this item has a draft.
+      def draft?
+        send(self.class.draft_association_name).present?
+      end
+
+      def draft_at(timestamp, reify_options = {})
+        v = send(self.class.versions_association_name).following(timestamp).first
+        v ? v.reify(reify_options) : self
+      end
+
+      # Creates object and records a draft for the object's creation. Returns `true` or `false` depending on whether or not
+      # the objects passed validation and the save was successful.
+      def draft_creation
+        transaction do
+          # We want to save the draft after create
+          return false unless self.save
+
+          data = {
+            :item      => self,
+            :event     => 'create',
+            :whodunnit => Draftsman.whodunnit,
+            :object    => object_to_string_for_draft
+          }
+          data[:object_changes] = Draftsman.serializer.dump(changes_for_draftsman(previous_changes: true)) if track_object_changes_for_draft?
+          data = merge_metadata_for_draft(data)
+
+          send "build_#{self.class.draft_association_name}", data
+
+          if send(self.class.draft_association_name).save
+            write_attribute "#{self.class.draft_association_name}_id", send(self.class.draft_association_name).id
+            self.update_column "#{self.class.draft_association_name}_id", send(self.class.draft_association_name).id
+            return true
+          else
+            raise ActiveRecord::Rollback and return false
+          end
+        end
+      end
+
+      # Trashes object and records a draft for a `destroy` event.
+      def draft_destroy
+        transaction do
+          data = {
+            :item      => self,
+            :event     => 'destroy',
+            :whodunnit => Draftsman.whodunnit,
+            :object    => object_to_string_for_draft
+          }
+
+          # Stash previous draft in case it needs to be reverted later
+          if self.draft?
+            data[:previous_draft] = Draftsman.serializer.dump(send(self.class.draft_association_name).attributes)
+          end
+
+          data = merge_metadata_for_draft(data)
+
+          if send(self.class.draft_association_name).present?
+            send(self.class.draft_association_name).update_attributes! data
+          else
+            send("build_#{self.class.draft_association_name}", data)
+            send(self.class.draft_association_name).save!
+            send "#{self.class.draft_association_name}_id=", send(self.class.draft_association_name).id
+            self.update_column "#{self.class.draft_association_name}_id", send(self.class.draft_association_name).id
+          end
+
+          trash!
+
+          # Mock `dependent: :destroy` behavior for all trashable associations
+          dependent_associations = self.class.reflect_on_all_associations(:has_one) + self.class.reflect_on_all_associations(:has_many)
+
+          dependent_associations.each do |association|
+
+            if association.klass.draftable? && association.options.has_key?(:dependent) && association.options[:dependent] == :destroy
+              dependents = association.macro == :has_one ? [self.send(association.name)] : self.send(association.name)
+
+              dependents.each do |dependent|
+                dependent.draft_destroy unless dependent.draft? && dependent.send(dependent.class.draft_association_name).destroy?
+              end
+            end
+          end
+        end
+      end
+
+      # Updates object and records a draft for an `update` event. If the draft is being updated to the object's original
+      # state, the draft is destroyed. Returns `true` or `false` depending on if the object passed validation and the save
+      # was successful.
+      def draft_update
+        transaction do
+          save_only_columns_for_draft
+
+          # We want to save the draft before update
+          return false unless self.valid?
+
+          # If updating a creation draft, also update this item
+          if self.draft? && send(self.class.draft_association_name).create?
+            data = {
+              :item      => self,
+              :whodunnit => Draftsman.whodunnit,
+              :object    => object_to_string_for_draft
+            }
+
+            if track_object_changes_for_draft?
+              data[:object_changes] = Draftsman.serializer.dump(changes_for_draftsman(changed_from: self.send(self.class.draft_association_name).changeset))
+            end
+
+            data = merge_metadata_for_draft(data)
+            send(self.class.draft_association_name).update_attributes data
+
+            self.save
+          # Destroy the draft if this record has changed back to the original record
+          elsif changed_to_original_for_draft?
+            send(self.class.draft_association_name).destroy
+            send "#{self.class.draft_association_name}_id=", nil
+            self.update_column "#{self.class.draft_association_name}_id", nil
+            true
+          # Save a draft if record is changed notably
+          elsif changed_notably_for_draft?
+            data = {
+              :item      => self,
+              :whodunnit => Draftsman.whodunnit,
+              :object    => object_to_string_for_draft
+            }
+            data = merge_metadata_for_draft(data)
+
+            # If there's already a draft, update it
+            if send(self.class.draft_association_name).present?
+              if track_object_changes_for_draft?
+                data[:object_changes] = Draftsman.serializer.dump(changes_for_draftsman)
+              end
+
+              send(self.class.draft_association_name).update_attributes data
+            # If there's not draft, create an update draft
+            else
+              data[:event]          = 'update'
+              data[:object_changes] = Draftsman.serializer.dump(changes_for_draftsman) if track_object_changes_for_draft?
+              send "build_#{self.class.draft_association_name}", data
+              
+              if send(self.class.draft_association_name).save
+                write_attribute "#{self.class.draft_association_name}_id", send(self.class.draft_association_name).id
+                self.update_column "#{self.class.draft_association_name}_id", send(self.class.draft_association_name).id
+              else
+                raise ActiveRecord::Rollback and return false
+              end
+            end
+          # If record is a draft and not changed notably, then update the draft
+          elsif self.draft?
+            data = {
+              :item      => self,
+              :whodunnit => Draftsman.whodunnit,
+              :object    => object_to_string_for_draft
+            }
+            data[:object_changes] = Draftsman.serializer.dump(changes_for_draftsman(changed_from: @object.draft.changeset)) if track_object_changes_for_draft?
+            data = merge_metadata_for_draft(data)
+
+            send(self.class.draft_association_name).update_attributes data
+          # Otherwise, just save the record
+          else
+            self.save
+          end
+        end
+      rescue Exception => e
+        false
+      end
+
+      # Returns serialized object representing this drafted item.
+      def object_to_string_for_draft(object = nil)
+        object ||= self
+
+        _attrs = object.attributes.except(*self.class.draftsman_options[:skip]).tap do |attributes|
+          self.class.serialize_attributes_for_draftsman attributes
+        end
+
+        Draftsman.serializer.dump(_attrs)
+      end
+
+      # Returns whether or not this item has been published at any point in its lifecycle.
+      def published?
+        self.published_at.present?
+      end
+
+      # Returns whether or not this item has been trashed
+      def trashed?
+        send(self.class.trashed_at_attribute_name).present?
+      end
+
+    private
+
+      # Returns changes on this object, excluding attributes defined in the options for `:ignore` and `:skip`.
+      def changed_and_not_ignored_for_draft(options = {})
+        options[:previous_changes] ||= false
+
+        my_changed = options[:previous_changes] ? previous_changes.keys : self.changed
+
+        ignore = self.class.draftsman_options[:ignore]
+        skip   = self.class.draftsman_options[:skip]
+        my_changed - ignore - skip
+      end
+
+      # Returns whether or not this instance has changes that should trigger a new draft.
+      def changed_notably_for_draft?
+        notably_changed_attributes_for_draft.any?
+      end
+
+      # Returns whether or not the updates change this draft back to the original state
+      def changed_to_original_for_draft?
+        send(self.draft_association_name).present? && send(self.class.draft_association_name).update? && !changed_notably_for_draft?
+      end
+
+      # Returns array of attributes that have changed for the object.
+      def changes_for_draftsman(options = {})
+        options[:changed_from]     ||= {}
+        options[:previous_changes] ||= false
+
+        my_changes = options[:previous_changes] ? self.previous_changes : self.changes
+
+        new_changes = my_changes.delete_if do |key, value|
+          !notably_changed_attributes_for_draft(previous_changes: options[:previous_changes]).include?(key)
+        end.tap do |changes|
+          self.class.serialize_draft_attribute_changes(changes) # Use serialized value for attributes when necessary
+        end
+
+        new_changes.each do |attribute, value|
+          new_changes[attribute][0] = options[:changed_from][attribute][0] if options[:changed_from].has_key?(attribute)
+        end
+
+        # We need to merge any previous changes so they are not lost on further updates before committing or
+        # reverting
+        options[:changed_from].merge new_changes
+      end
+
+      # Returns draft class.
+      def draft_class
+        self.draft_class_name.constantize
+      end
+
+      # Merges model-level metadata from `meta` and `controller_info` into draft object.
+      def merge_metadata_for_draft(data)
+        # First, we merge the model-level metadata in `meta`.
+        draftsman_options[:meta].each do |attribute, value|
+          data[attribute] =
+            if value.respond_to?(:call)
+              value.call(self)
+            elsif value.is_a?(Symbol) && respond_to?(value)
+              # if it is an attribute that is changing, be sure to grab the current version
+              if has_attribute?(value) && send("#{value}_changed?".to_sym)
+                send("#{value}_was".to_sym)
+              else
+                send(value)
+              end
+            else
+              value
+            end
+        end
+
+        # Second, we merge any extra data from the controller (if available).
+        data.merge(Draftsman.controller_info || {})
+      end
+
+      # Returns array of attributes that were changed to trigger a draft.
+      def notably_changed_attributes_for_draft(options = {})
+        options[:previous_changes] ||= false
+
+        only = self.class.draftsman_options[:only]
+        only.empty? ? changed_and_not_ignored_for_draft(previous_changes: options[:previous_changes]) : (changed_and_not_ignored_for_draft(previous_changes: options[:previous_changes]) & only)
+      end
+
+      # Save columns outside of the `only` option directly to master table
+      def save_only_columns_for_draft
+        if self.class.draftsman_options[:only].any?
+          only_changes = {}
+          only_changed_attributes = self.changed - self.class.draftsman_options[:only]
+          
+          only_changed_attributes.each do |attribute|
+            only_changes[attribute] = self.changes[attribute].last
+          end
+
+          self.update_columns only_changes if only_changes.any?
+        end
+      end
+
+      # Returns whether or not the draft class includes an `object_changes` attribute.
+      def track_object_changes_for_draft?
+        draft_class.column_names.include? 'object_changes'
+      end
+
+      # Sets `trashed_at` attribute to now and saves to the database immediately.
+      def trash!
+        write_attribute self.class.trashed_at_attribute_name, Time.now
+        self.update_column self.class.trashed_at_attribute_name, send(self.class.trashed_at_attribute_name)
+      end
+    end
+  end
+end

data/lib/draftsman/serializers/json.rb

@@ -0,0 +1,17 @@
+require 'active_support/json'
+
+module Draftsman
+  module Serializers
+    module Json
+      extend self # makes all instance methods become module methods as well
+
+      def load(string)
+        ActiveSupport::JSON.decode string
+      end
+
+      def dump(object)
+        ActiveSupport::JSON.encode object
+      end
+    end
+  end
+end

data/lib/draftsman/serializers/yaml.rb

@@ -0,0 +1,17 @@
+require 'yaml'
+
+module Draftsman
+  module Serializers
+    module Yaml
+      extend self # makes all instance methods become module methods as well
+
+      def load(string)
+        YAML.load string
+      end
+
+      def dump(object)
+        YAML.dump object
+      end
+    end
+  end
+end

data/lib/draftsman/version.rb

@@ -0,0 +1,3 @@
+module Draftsman
+  VERSION = '0.1.0'
+end

data/lib/draftsman.rb

@@ -0,0 +1,101 @@
+require 'draftsman/config'
+require 'draftsman/model'
+
+# Require all frameworks and serializers
+Dir[File.join(File.dirname(__FILE__), 'draftsman', 'frameworks', '*.rb')].each { |file| require file }
+Dir[File.join(File.dirname(__FILE__), 'draftsman', 'serializers', '*.rb')].each { |file| require file }
+
+# Draftsman's module methods can be called in both models and controllers.
+module Draftsman
+  # Returns whether or not ActiveRecord is configured to require mass assignment whitelisting via `attr_accessible`.
+  def self.active_record_protected_attributes?
+    @active_record_protected_attributes ||= ActiveRecord::VERSION::STRING.to_f < 4.0 || defined?(ProtectedAttributes)
+  end
+
+  # Returns any information from the controller that you want Draftsman to store.
+  #
+  # See `Draftsman::Controller#info_for_draftsman`.
+  def self.controller_info
+    draftsman_store[:controller_info]
+  end
+
+  # Sets any information from the controller that you want Draftsman to store. By default, this is set automatically by
+  # a before filter.
+  def self.controller_info=(value)
+    draftsman_store[:controller_info] =  value
+  end
+
+  # Returns default class name used for drafts.
+  def self.draft_class_name
+    draftsman_store[:draft_class_name]
+  end
+
+  # Sets default class name to use for drafts.
+  def self.draft_class_name=(class_name)
+    draftsman_store[:draft_class_name] = class_name
+  end
+
+  # Set the field which records when a draft was created.
+  def self.timestamp_field=(field_name)
+    Draftsman.config.timestamp_field = field_name
+  end
+
+  # Returns the field which records when a draft was created.
+  def self.timestamp_field
+    Draftsman.config.timestamp_field
+  end
+
+  # Returns serializer to use for `object`, `object_changes`, and `previous_draft` columns.
+  def self.serializer
+    Draftsman.config.serializer
+  end
+
+  # Sets serializer to use for `object`, `object_changes`, and `previous_draft` columns.
+  def self.serializer=(value)
+    Draftsman.config.serializer = value
+  end
+
+  # Returns who is reponsible for any changes that occur.
+  def self.whodunnit
+    draftsman_store[:whodunnit]
+  end
+
+  # Sets who is responsible for any changes that occur.
+  # You would normally use this in a migration or on the console,
+  # when working with models directly.  In a controller, it is set
+  # automatically to the `current_user`.
+  def self.whodunnit=(value)
+    draftsman_store[:whodunnit] = value
+  end
+
+private
+
+  # Thread-safe hash to hold Draftman's data. Initializing with needed default values.
+  def self.draftsman_store
+    Thread.current[:draft] ||= { :draft_class_name => 'Draftsman::Draft' }
+  end
+
+  # Returns Draftman's configuration object.
+  def self.config
+    @@config ||= Draftsman::Config.instance
+  end
+
+  def self.configure
+    yield config
+  end
+end
+
+# Draft model class.
+require 'draftsman/draft'
+
+# Inject `Draftsman::Model` into ActiveRecord classes.
+ActiveSupport.on_load(:active_record) do
+  include Draftsman::Model
+end
+
+# Inject `Draftsman::Rails::Controller` into Rails controllers.
+if defined?(ActionController)
+  ActiveSupport.on_load(:action_controller) do
+    include Draftsman::Rails::Controller
+  end
+end

data/lib/generators/draftsman/install_generator.rb

@@ -0,0 +1,27 @@
+require 'rails/generators'
+require 'rails/generators/migration'
+require 'rails/generators/active_record'
+
+module Draftsman
+  class InstallGenerator < ::Rails::Generators::Base
+    include ::Rails::Generators::Migration
+
+    desc 'Generates (but does not run) a migration to add a drafts table.'
+    source_root File.expand_path('../templates', __FILE__)
+    class_option :skip_initializer, :type => :boolean, :default => false, :desc => 'Skip generation of the boilerplate initializer at `config/initializers/draftsman.rb`.'
+    class_option :with_changes, :type => :boolean, :default => false, :desc => 'Store changeset (diff) with each draft'
+
+    def create_migration_file
+      migration_template 'create_drafts.rb', 'db/migrate/create_drafts.rb'
+      migration_template 'add_object_changes_column_to_drafts.rb', 'db/migrate/add_object_changes_column_to_drafts.rb' if options.with_changes?
+    end
+
+    def self.next_migration_number(dirname)
+      ActiveRecord::Generators::Base.next_migration_number(dirname)
+    end
+
+    def copy_config
+      template 'config/initializers/draftsman.rb' unless options.skip_initializer?
+    end
+  end
+end

data/lib/generators/draftsman/templates/add_object_changes_column_to_drafts.rb

@@ -0,0 +1,9 @@
+class AddObjectChangesColumnToDrafts < ActiveRecord::Migration
+  def self.up
+    add_column :drafts, :object_changes, :text
+  end
+
+  def self.down
+    remove_column :drafts, :object_changes
+  end
+end

data/lib/generators/draftsman/templates/config/initializers/draftsman.rb

@@ -0,0 +1,11 @@
+# Override global `draft` class. For example, perhaps you want your own class at `app/models/draft.rb` that adds
+# extra attributes, validations, associations, etc. Be sure that this new model class extends `Draftsman::Draft`.
+# Draftsman.draft_class_name = 'Draftsman::Draft'
+
+# Serializer for `object`, `object_changes`, and `previous_draft` columns. To use the JSON serializer, change to
+# `Draftsman::Serializers::Json`. You could implement your own serializer if you really wanted to. See files in
+# `lib/draftsman/serializers`.
+# Draftsman.serializer = Draftsman::Serializers::Json
+
+# Field which records when a draft was created.
+# Draftsman.timestamp_field = :created_at

data/lib/generators/draftsman/templates/create_drafts.rb

@@ -0,0 +1,22 @@
+class CreateDrafts < ActiveRecord::Migration
+  def change
+    create_table :drafts do |t|
+      t.string  :item_type, :null => false
+      t.integer :item_id,   :null => false
+      t.string  :event,     :null => false
+      t.string  :whodunnit#  :null => false
+      t.text    :object
+      t.text    :previous_draft
+      t.timestamps
+    end
+
+    change_table :drafts do |t|
+      t.index :item_type
+      t.index :item_id
+      t.index :event
+      t.index :whodunnit
+      t.index :created_at
+      t.index :updated_at
+    end
+  end
+end

data/spec/controllers/informants_controller_spec.rb

@@ -0,0 +1,27 @@
+require 'spec_helper'
+
+# Tests controller `info_for_draftsman` method
+describe InformantsController do
+  let(:trashable) { Trashable.create!(:name => 'Bob') }
+
+  describe :create do
+    before { post :create }
+    subject { Draftsman::Draft.last }
+    its(:ip) { should eql '123.45.67.89' }
+    its(:user_agent) { should eql '007' }
+  end
+
+  describe :update do
+    before { put :update, :id => trashable.id }
+    subject { Draftsman::Draft.last }
+    its(:ip) { should eql '123.45.67.89' }
+    its(:user_agent) { should eql '007' }
+  end
+
+  describe :destroy do
+    before { delete :destroy, :id => trashable.id }
+    subject { Draftsman::Draft.last }
+    its(:ip) { should eql '123.45.67.89' }
+    its(:user_agent) { should eql '007' }
+  end
+end