brianjlandau-vestal_versions 1.3.0

data/lib/vestal_versions/creation.rb

@@ -0,0 +1,85 @@
+module VestalVersions
+  # Adds the functionality necessary to control version creation on a versioned instance of
+  # ActiveRecord::Base.
+  module Creation
+    def self.included(base) # :nodoc:
+      base.class_eval do
+        extend ClassMethods
+        include InstanceMethods
+
+        after_update :create_version, :if => :create_version?
+        after_update :update_version, :if => :update_version?
+
+        class << self
+          alias_method_chain :prepare_versioned_options, :creation
+        end
+      end
+    end
+
+    # Class methods added to ActiveRecord::Base to facilitate the creation of new versions.
+    module ClassMethods
+      # Overrides the basal +prepare_versioned_options+ method defined in VestalVersions::Options
+      # to extract the <tt>:only</tt> and <tt>:except</tt> options into +vestal_versions_options+.
+      def prepare_versioned_options_with_creation(options)
+        result = prepare_versioned_options_without_creation(options)
+
+        self.vestal_versions_options[:only] = Array(options.delete(:only)).map(&:to_s).uniq if options[:only]
+        self.vestal_versions_options[:except] = Array(options.delete(:except)).map(&:to_s).uniq if options[:except]
+
+        result
+      end
+    end
+
+    # Instance methods that determine whether to save a version and actually perform the save.
+    module InstanceMethods
+      private
+        # Returns whether a new version should be created upon updating the parent record.
+        def create_version?
+          !version_changes.blank?
+        end
+
+        # Creates a new version upon updating the parent record.
+        def create_version(attributes = nil)
+          versions.create(attributes || version_attributes)
+          reset_version_changes
+          reset_version
+        end
+
+        # Returns whether the last version should be updated upon updating the parent record.
+        # This method is overridden in VestalVersions::Control to account for a control block that
+        # merges changes onto the previous version.
+        def update_version?
+          false
+        end
+
+        # Updates the last version's changes by appending the current version changes.
+        def update_version
+          return create_version unless v = versions.last
+          v.modifications_will_change!
+          v.update_attributes(:modifications => v.changes.append_changes(version_changes))
+          reset_version_changes
+          reset_version
+        end
+
+        # Returns an array of column names that should be included in the changes of created
+        # versions. If <tt>vestal_versions_options[:only]</tt> is specified, only those columns
+        # will be versioned. Otherwise, if <tt>vestal_versions_options[:except]</tt> is specified,
+        # all columns will be versioned other than those specified. Without either option, the
+        # default is to version all columns. At any rate, the four "automagic" timestamp columns
+        # maintained by Rails are never versioned.
+        def versioned_columns
+          case
+            when vestal_versions_options[:only] then self.class.column_names & vestal_versions_options[:only]
+            when vestal_versions_options[:except] then self.class.column_names - vestal_versions_options[:except]
+            else self.class.column_names
+          end - %w(created_at created_on updated_at updated_on)
+        end
+
+        # Specifies the attributes used during version creation. This is separated into its own
+        # method so that it can be overridden by the VestalVersions::Users feature.
+        def version_attributes
+          {:modifications => version_changes, :number => last_version + 1}
+        end
+    end
+  end
+end

data/lib/vestal_versions/deletion.rb

@@ -0,0 +1,46 @@
+module VestalVersions
+  # Allows version creation to occur conditionally based on given <tt>:if</tt> and/or
+  # <tt>:unless</tt> options.
+  module Deletion
+    def self.included(base) # :nodoc:
+      base.class_eval do
+        extend ClassMethods
+        include InstanceMethods
+
+        before_destroy :create_destroyed_version, :if => :delete_version?
+
+        class << self
+          alias_method_chain :prepare_versioned_options, :deletion
+        end
+      end
+    end
+
+    # Class methods on ActiveRecord::Base 
+    module ClassMethods
+      # After the original +prepare_versioned_options+ method cleans the given options, this alias
+      # also extracts the <tt>:depedent</tt> if it set to <tt>:tracking</tt> 
+      def prepare_versioned_options_with_deletion(options)
+        result = prepare_versioned_options_without_deletion(options)
+        if result[:dependent] == :tracking
+          self.vestal_versions_options[:track_destroy] = true
+          options.delete(:dependent)
+        end
+
+        result
+      end
+    end
+
+    module InstanceMethods
+      private
+
+        def delete_version?
+          vestal_versions_options[:track_destroy]
+        end
+
+        def create_destroyed_version
+          create_version({:modifications => attributes, :number => last_version + 1, :tag => 'deleted'})
+        end
+
+    end
+  end
+end

data/lib/vestal_versions/options.rb

@@ -0,0 +1,45 @@
+module VestalVersions
+  # Provides +versioned+ options conversion and cleanup.
+  module Options
+    def self.included(base) # :nodoc:
+      base.class_eval do
+        extend ClassMethods
+      end
+    end
+
+    # Class methods that provide preparation of options passed to the +versioned+ method.
+    module ClassMethods
+      # The +prepare_versioned_options+ method has three purposes:
+      # 1. Populate the provided options with default values where needed
+      # 2. Prepare options for use with the +has_many+ association
+      # 3. Save user-configurable options in a class-level variable
+      #
+      # Options are given priority in the following order:
+      # 1. Those passed directly to the +versioned+ method
+      # 2. Those specified in an initializer +configure+ block
+      # 3. Default values specified in +prepare_versioned_options+
+      #
+      # The method is overridden in feature modules that require specific options outside the
+      # standard +has_many+ associations.
+      def prepare_versioned_options(options)
+        options.symbolize_keys!
+        options.reverse_merge!(Configuration.options)
+        options.reverse_merge!(
+          :class_name => 'VestalVersions::Version',
+          :dependent => :delete_all
+        )
+        options.reverse_merge!(
+          :order => "#{options[:class_name].constantize.table_name}.number ASC"
+        )
+
+        class_inheritable_accessor :vestal_versions_options
+        self.vestal_versions_options = options.dup
+
+        options.merge!(
+          :as => :versioned,
+          :extend => Array(options[:extend]).unshift(Versions)
+        )
+      end
+    end
+  end
+end

data/lib/vestal_versions/reload.rb

@@ -0,0 +1,22 @@
+module VestalVersions
+  # Ties into the existing ActiveRecord::Base#reload method to ensure that version information
+  # is properly reset.
+  module Reload
+    def self.included(base) # :nodoc:
+      base.class_eval do
+        include InstanceMethods
+
+      end
+    end
+
+    # Adds instance methods into ActiveRecord::Base to tap into the +reload+ method.
+    module InstanceMethods
+      # Overrides ActiveRecord::Base#reload, resetting the instance-variable-cached version number
+      # before performing the original +reload+ method.
+      def reload(*args)
+        reset_version
+        super
+      end
+    end
+  end
+end

data/lib/vestal_versions/reset.rb

@@ -0,0 +1,28 @@
+module VestalVersions
+  # Adds the ability to "reset" (or hard revert) a versioned ActiveRecord::Base instance.
+  module Reset
+    def self.included(base) # :nodoc:
+      base.class_eval do
+        include InstanceMethods
+      end
+    end
+
+    # Adds the instance methods required to reset an object to a previous version.
+    module InstanceMethods
+      # Similar to +revert_to!+, the +reset_to!+ method reverts an object to a previous version,
+      # only instead of creating a new record in the version history, +reset_to!+ deletes all of
+      # the version history that occurs after the version reverted to.
+      #
+      # The action taken on each version record after the point of reversion is determined by the
+      # <tt>:dependent</tt> option given to the +versioned+ method. See the +versioned+ method
+      # documentation for more details.
+      def reset_to!(value)
+        if saved = skip_version{ revert_to!(value) }
+          versions.send(:delete_records, versions.after(value))
+          reset_version
+        end
+        saved
+      end
+    end
+  end
+end

data/lib/vestal_versions/reversion.rb

@@ -0,0 +1,92 @@
+module VestalVersions
+  # Enables versioned ActiveRecord::Base instances to revert to a previously saved version.
+  module Reversion
+    def self.included(base) # :nodoc:
+      base.class_eval do
+        include InstanceMethods
+      end
+    end
+
+    # Provides the base instance methods required to revert a versioned instance.
+    module InstanceMethods
+      # Returns the current version number for the versioned object.
+      def version
+        @version ||= last_version
+      end
+
+      # Accepts a value corresponding to a specific version record, builds a history of changes
+      # between that version and the current version, and then iterates over that history updating
+      # the object's attributes until the it's reverted to its prior state.
+      #
+      # The single argument should adhere to one of the formats as documented in the +at+ method of
+      # VestalVersions::Versions.
+      #
+      # After the object is reverted to the target version, it is not saved. In order to save the
+      # object after the reversion, use the +revert_to!+ method.
+      #
+      # The version number of the object will reflect whatever version has been reverted to, and
+      # the return value of the +revert_to+ method is also the target version number.
+      def revert_to(value)
+        self.class.reflections.each do |association, reflection|
+          self.send(association).reset if reflection.macro == :has_many
+        end
+        
+        to_number = versions.number_at(value)
+
+        changes_between(version, to_number).each do |attribute, change|
+          write_attribute(attribute, change.last)
+        end
+        
+        reset_version(to_number)
+      end
+
+      # Behaves similarly to the +revert_to+ method except that it automatically saves the record
+      # after the reversion. The return value is the success of the save.
+      def revert_to!(value)
+        revert_to(value)
+        reset_version if saved = save
+        saved
+      end
+
+      # Returns a boolean specifying whether the object has been reverted to a previous version or
+      # if the object represents the latest version in the version history.
+      def reverted?
+        version != last_version
+      end
+
+
+      private
+
+        # Mixes in the reverted_from value if it is currently within a revert
+        def version_attributes
+          attributes = super
+
+          if @reverted_from.nil?
+            attributes
+          else
+            attributes.merge(:reverted_from => @reverted_from)
+          end
+        end
+
+      
+        # Returns the number of the last created version in the object's version history.
+        #
+        # If no associated versions exist, the object is considered at version 1.
+        def last_version
+          @last_version ||= versions.maximum(:number) || 1
+        end
+
+        # Clears the cached version number instance variables so that they can be recalculated.
+        # Useful after a new version is created.
+        def reset_version(version = nil)
+          if version.nil?
+            @last_version = nil
+            @reverted_from = nil
+          else
+            @reverted_from = version
+          end
+          @version = version
+        end
+    end
+  end
+end

data/lib/vestal_versions/tagging.rb

@@ -0,0 +1,54 @@
+module VestalVersions
+  # Allows specific versions to be tagged with a custom string. Useful for assigning a more
+  # meaningful value to a version for the purpose of reversion.
+  module Tagging
+    def self.included(base) # :nodoc:
+      Version.send(:include, VersionMethods)
+
+      base.class_eval do
+        include InstanceMethods
+      end
+    end
+
+    # Adds an instance method which allows version tagging through the parent object.
+    module InstanceMethods
+      # Accepts a single string argument which is attached to the version record associated with
+      # the current version number of the parent object.
+      #
+      # Returns the given tag if successful, nil if not. Tags must be unique within the scope of
+      # the parent object. Tag creation will fail if non-unique.
+      #
+      # Version records corresponding to version number 1 are not typically created, but one will
+      # be built to house the given tag if the parent object's current version number is 1.
+      def tag_version(tag)
+        v = versions.at(version) || versions.build(:number => 1)
+        v.tag!(tag)
+      end
+    end
+
+    # Instance methods included into VestalVersions::Version to enable version tagging.
+    module VersionMethods
+      def self.included(base) # :nodoc:
+        base.class_eval do
+          validates_uniqueness_of :tag, :scope => [:versioned_id, :versioned_type], :if => :validate_tags?
+        end
+      end
+
+      # Attaches the given string to the version tag column. If the uniqueness validation fails,
+      # nil is returned. Otherwise, the given string is returned.
+      def tag!(tag)
+        write_attribute(:tag, tag)
+        save ? tag : nil
+      end
+
+      # Simply returns a boolean signifying whether the version instance has a tag value attached.
+      def tagged?
+        !tag.nil?
+      end
+      
+      def validate_tags?
+        tagged? && tag != 'deleted'
+      end
+    end
+  end
+end

data/lib/vestal_versions/users.rb

@@ -0,0 +1,56 @@
+module VestalVersions
+  # Provides a way for information to be associated with specific versions as to who was
+  # responsible for the associated update to the parent.
+  module Users
+    def self.included(base) # :nodoc:
+      Version.send(:include, VersionMethods)
+
+      base.class_eval do
+        include InstanceMethods
+
+        attr_accessor :updated_by
+      end
+    end
+
+    # Methods added to versioned ActiveRecord::Base instances to enable versioning with additional
+    # user information.
+    module InstanceMethods
+      private
+        # Overrides the +version_attributes+ method to include user information passed into the
+        # parent object, by way of a +updated_by+ attr_accessor.
+        def version_attributes
+          super.merge(:user => updated_by)
+        end
+    end
+
+    # Instance methods added to VestalVersions::Version to accomodate incoming user information.
+    module VersionMethods
+      def self.included(base) # :nodoc:
+        base.class_eval do
+          belongs_to :user, :polymorphic => true
+
+          alias_method_chain :user, :name
+          alias_method_chain :user=, :name
+        end
+      end
+
+      # Overrides the +user+ method created by the polymorphic +belongs_to+ user association. If
+      # the association is absent, defaults to the +user_name+ string column. This allows
+      # VestalVersions::Version#user to either return an ActiveRecord::Base object or a string,
+      # depending on what is sent to the +user_with_name=+ method.
+      def user_with_name
+        user_without_name || user_name
+      end
+
+      # Overrides the +user=+ method created by the polymorphic +belongs_to+ user association.
+      # Based on the class of the object given, either the +user+ association columns or the
+      # +user_name+ string column is populated.
+      def user_with_name=(value)
+        case value
+          when ActiveRecord::Base then self.user_without_name = value
+          else self.user_name = value
+        end
+      end
+    end
+  end
+end

data/lib/vestal_versions/version.rb

@@ -0,0 +1,76 @@
+module VestalVersions
+  # The ActiveRecord model representing versions.
+  class Version < ActiveRecord::Base
+    include Comparable
+
+    # Associate polymorphically with the parent record.
+    belongs_to :versioned, :polymorphic => true
+
+    # ActiveRecord::Base#changes is an existing method, so before serializing the +changes+ column,
+    # the existing +changes+ method is undefined. The overridden +changes+ method pertained to
+    # dirty attributes, but will not affect the partial updates functionality as that's based on
+    # an underlying +changed_attributes+ method, not +changes+ itself.
+    undef_method :changes
+    def changes
+      self[:modifications]
+    end
+    serialize :modifications, Hash
+
+    # In conjunction with the included Comparable module, allows comparison of version records
+    # based on their corresponding version numbers, creation timestamps and IDs.
+    def <=>(other)
+      [number, created_at, id].map(&:to_i) <=> [other.number, other.created_at, other.id].map(&:to_i)
+    end
+
+    # Returns whether the version has a version number of 1. Useful when deciding whether to ignore
+    # the version during reversion, as initial versions have no serialized changes attached. Helps
+    # maintain backwards compatibility.
+    def initial?
+      number == 1
+    end
+    
+    # Returns the original version number that this version was.
+    def original_number
+      if reverted_from.nil?
+        number
+      else
+        version = versioned.versions.at(reverted_from)
+        version.nil? ? 1 : version.original_number
+      end
+    end
+
+    def restore!
+      model = restore
+      
+      if model
+        model.save!
+        destroy
+      end
+      
+      model
+    end
+    
+    def restore
+      if tag == 'deleted'
+        attrs = modifications
+
+        class_name = attrs['type'].blank? ? versioned_type : attrs['type']
+        klass = class_name.constantize
+        model = klass.new
+
+        attrs.each do |k, v|
+          begin
+            model.send "#{k}=", v
+          rescue NoMethodError
+            logger.warn "Attribute #{k} does not exist on #{class_name} (Version id: #{id})." rescue nil
+          end
+        end
+
+        model
+      else
+        latest_version = self.class.find(:first, :conditions => {:versioned_id => versioned_id, :versioned_type => versioned_type, :tag => 'deleted'})
+        latest_version.nil? ? nil : latest_version.restore
+      end
+    end
+  end
+end