acts_as_soft_delete_by_field 1.0.2

data/README

@@ -0,0 +1,114 @@
+Soft Delete By Field
+===================
+
+Provides mechanism for soft delete functionality. Soft delete means that on
+delete, an object is flagged as deleted rather than being removed from the
+database. This makes it far easier to recover objects that have
+been deleted by mistake.
+
+This soft delete mechanism uses a field in a models table, to flag and
+record the date of deletion.
+
+Requirements
+------------
+This plugin is designed for Rails 3. The syntax of the scope options
+will not work with Rails 2.
+
+The model object needs to have a datetime field, that on
+delete will be set to the current time. By default, this field should
+be :deleted_at, but you can also specify your own field.
+
+Usage
+-----
+
+  class Thing < ActiveRecord::Base
+
+    acts_as_soft_delete_by_field
+
+  end
+
+If you wish to use a field other than :deleted_at, for example :soft_deleted_at,
+you can do this via the acts_as_soft_delete_by_field declaration:
+
+  class Thing < ActiveRecord::Base
+
+    acts_as_soft_delete_by_field(:soft_deleted_at)
+
+  end
+
+Functionality
+-------------
+Adds 'extant' and 'deleted' scopes to the model. For example, if added
+to a Thing model, would allow you to do the following:
+
+     thing.soft_delete   ---- Soft deletes an instance of thing
+
+     Thing.extant        ---- Finds all things that are not deleted
+     Thing.deleted.count ---- Counts how many things have been deleted
+
+     Thing.extant.find(
+       :all,
+       :conditions => ["colour = ?", 'red']
+     )                   ---- Finds all extant things that have colour set as red
+
+     Thing.extant.where(:colour => 'red')      ---- As above using where
+
+
+Also if Box has_many things
+
+     box.things.deleted ---- Finds all the deleted things in the box
+
+Note that Thing's delete instance method is not effected by this functionality
+so:
+
+    thing.soft_delete  --- alters the thing instance to be flagged as deleted
+    thing.delete       --- deletes the thing from the database.
+
+If you want delete actions to soft_delete, overwrite delete:
+
+  class Thing
+
+    acts_as_soft_delete_by_field
+
+    def delete
+      soft_delete
+    end
+
+  end
+
+Callbacks
+---------
+
+There are also two callback methods: before_soft_delete and after_soft_delete
+Overwrite these methods in the model to use them. For example:
+
+  class Thing
+    acts_as_soft_delete_by_field
+
+    def after_soft_delete
+      puts "Thing soft deleted"
+    end
+  end
+
+Now, when a thing is soft deleted, "Thing soft deleted" will printed be to the
+console.
+
+Testing
+-------
+
+A number of custom assertions are made available when this plugin is installed.
+They are held in the module ActsAsSoftDeleteByFieldAssertions. In particular,
+assert_soft_delete_working_for works through each of the assertions and can
+be used as a test that soft deletion is working correctly on any model where
+it is used.
+
+   class ThingTest < ActiveSupport::TestCase
+
+     def test_soft_delete
+       assert_soft_delete_working_for(Thing.first)
+     end
+
+   end
+
+Copyright (c) 2011 Rob Nichols, released under the MIT license
+

data/Rakefile

@@ -0,0 +1,23 @@
+require 'rake'
+require 'rake/testtask'
+require 'rdoc/task'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the acts_as_soft_delete plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the acts_as_soft_delete plugin.'
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'ActsAsSoftDelete'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/lib/acts_as_soft_delete_by_field.rb

@@ -0,0 +1,5 @@
+require 'soft_delete_by_field'
+require 'acts_as_soft_delete_by_field_assertions'
+
+ActiveRecord::Base.send(:include, ActiveRecord::Acts::SoftDeleteByField)
+ActiveSupport::TestCase.send(:include, ActsAsSoftDeleteByFieldAssertions)

data/lib/acts_as_soft_delete_by_field_assertions.rb

@@ -0,0 +1,240 @@
+# Provides assertion methods that make it easier to test soft deletion functionality
+#
+# The soft delete functionality can be tested via:
+#
+#   class ThingTest < ActiveSupport::TestCase
+#
+#     def test_soft_delete
+#       assert_soft_delete_working_for(Thing.first)
+#     end
+#
+#   end
+#
+module ActsAsSoftDeleteByFieldAssertions
+
+  def assert_soft_delete_by_field_working_for(item)
+    # Using clones, as otherwise other assertions affected
+    @starting_number = item.class.count
+    assert_before_soft_delete_all_correct_for(item)
+    @start_time = Time.now
+    item.soft_delete
+    assert_extant_working_for(item)
+    assert_deleted_working_for(item)
+    assert_still_in_database_but_with_deleted_at_set(item)
+    assert_soft_deleted(item)
+    assert_recover_soft_deleted(item)
+    assert_deletion_prevented_if_reasons_not_to_delete_overwritten_with_method_returning_true(item.clone)
+    assert_deletion_prevented_if_reasons_not_to_delete_detected(item)
+    assert_before_soft_delete(item.clone)
+    assert_after_soft_delete(item.clone)
+  end
+  
+  def assert_soft_deleted(item)
+    assert_equal(true, item.reload.is_deleted?, error_messages_for(item, "Not deleted: #{item.inspect}"))
+  end
+
+  def assert_extant(item)
+    deletion_object_details = ". Deletion_object: #{@deletion_objects.inspect}" if @deletion_objects
+    assert_equal(true, item.reload.is_extant?,  error_messages_for(item, "Not extant: #{item.inspect}"))
+  end
+
+  def assert_get_request_to_delete_raises_error
+    login_as User.first
+    assert_raise RuntimeError do
+      get :delete
+    end
+  end
+
+  def assert_recover_soft_deleted(item)
+    item.recover_soft_deleted
+    assert_before_soft_delete_all_correct_for(item)
+  end
+
+  def assert_before_soft_delete_all_correct_for(item)
+    assert_all_extant(item)
+    assert_extant_includes(item)
+    assert_none_soft_deleted(item)
+    assert_extant(item)
+  end
+
+  def assert_extant_includes(item)
+    assert item.class.extant.include?(item)
+  end
+
+  def assert_all_extant(item)
+    assert_equal item.class.count, item.class.extant.count
+  end
+
+  def assert_none_soft_deleted(item)
+    assert_equal 0, item.class.deleted.count
+  end
+
+  def assert_extant_working_for(item)
+    assert_equal @starting_number - 1, item.class.extant.count
+    assert !item.class.extant.include?(item)
+  end
+
+  def assert_deleted_working_for(item)
+    assert_equal 1, item.class.deleted.count
+    assert_equal item, item.class.deleted.first
+  end
+
+  def assert_still_in_database_but_with_deleted_at_set(item)
+    assert_object_still_in_database(item)
+    assert_deleted_at_set_as_time_after_test_started_for(item)
+  end
+
+  def assert_deleted_at_set_as_time_after_test_started_for(object)
+    assert object.deleted_via_soft_delete_by_field_name_at >= @start_time, "Deletion occured before test was run (#{object.deleted_via_soft_delete_by_field_name_at})"
+  end
+
+  def assert_object_still_in_database(object)
+    assert_equal object, object.class.find(object.id)
+  end
+
+  def create_soft_deletion_objects(object, source_path)
+    @source_path = source_path
+    @object_class = object.class.to_s
+    @object_id = object.id.to_s
+    @deletion_objects = {
+        :source_path => @source_path,
+        :object_class => @object_class,
+        :object_id => @object_id
+    }
+  end
+
+  def assert_soft_deletion_via_delete_action(object, path)
+    create_deletion_objects_and_pass_to_delete(object, path)
+    assert_redirection_to_path(@source_path)
+    assert_soft_deleted(object)
+  end
+
+  def assert_failure_to_soft_delete_via_delete_action(object, path)
+    create_deletion_objects_and_pass_to_delete(object, path)
+    assert_redirection_to_path(@source_path)
+    assert_extant(object)
+  end
+
+  def create_deletion_objects_and_pass_to_delete(object, path)
+    create_soft_deletion_objects(object, path)
+    @deletion_objects
+    post :delete, @deletion_objects
+  end
+
+  def assert_undeletion_via_recover_soft_deleted_action(object, path)
+    object.soft_delete
+    create_deletion_objects_and_pass_to_recover_soft_deleted(object, path)
+    assert_redirection_to_path(@source_path)
+    assert_extant(object.reload)
+  end
+  
+  def create_deletion_objects_and_pass_to_recover_soft_deleted(object, path)
+    create_soft_deletion_objects(object, path)
+    @deletion_objects
+    post :recover_soft_deleted, @deletion_objects
+  end
+
+  def assert_deletion_prevented_if_reasons_not_to_delete_overwritten_with_method_returning_true(item)
+    if model_has_custom_reason_not_to_delete_defined(item)
+      # This test not valid in this case
+    else
+      assert_soft_deletion_working(item)
+      method_to_add_to_item = <<EOF
+
+  def reasons_not_to_delete?
+    true
+  end
+
+EOF
+
+      item.class_eval(method_to_add_to_item)
+      assert_reasons_not_to_delete_prevents_soft_deletion(item)
+    end
+  end
+
+  def assert_deletion_prevented_if_reasons_not_to_delete_detected(item)
+    if model_has_custom_reason_not_to_delete_defined(item)
+      # This test not valid in this case
+    else
+      assert_soft_deletion_working(item)
+      initial_reasons_not_to_delete = item.reasons_not_to_delete
+      item.reasons_not_to_delete = "Don't delete"
+      assert_reasons_not_to_delete_prevents_soft_deletion(item)
+      item.reasons_not_to_delete = initial_reasons_not_to_delete
+    end
+  end
+
+  def assert_before_soft_delete(item)
+    message = "Hello world"
+    assert_soft_deletion_working(item)
+    assert(!item.respond_to?(:goodbye))
+    method_to_add_to_item = <<EOF
+
+  def goodbye
+    '#{message}'
+  end
+
+EOF
+    item.class_eval(method_to_add_to_item)
+    item.soft_delete
+    assert item.is_deleted?, 'Item not deleted'
+    assert_equal message, item.goodbye
+  end
+
+  def assert_after_soft_delete(item)
+    message = 'Hello there'
+    assert_soft_deletion_working(item)
+    assert(!item.respond_to?(:hello))
+    method_to_add_to_item = <<EOF
+
+  def hello
+    '#{message}'
+  end
+
+EOF
+    item.class_eval(method_to_add_to_item)
+    item.soft_delete
+    assert item.is_deleted?, 'Item not deleted'
+    assert_equal message, item.hello
+  end
+
+
+  private
+  def error_messages_for(item, first_message)
+    error_messages = [first_message]
+    error_messages << item.errors.full_messages unless item.errors.empty?
+    error_messages << "Flash: #{@request.session['flash'].inspect}" if @request
+    error_messages << "Deletion_object: #{@deletion_objects.inspect}" if @deletion_objects
+    error_messages.join(". ")
+  end
+
+  def assert_extant_at_start_of_test(item)
+    assert(item.is_extant?, "Item must be extant at start of test #{item.inspect}")
+  end
+
+  def assert_reasons_not_to_delete_prevents_soft_deletion(item)
+    item.soft_delete
+    assert(item.is_extant?, "Item was deleted in spite of reasons_not_to_delete? being true")
+    assert_errors_on_base(item)
+  end
+
+  def assert_soft_deletion_working(item)
+    item.soft_delete
+    assert(item.is_deleted?, "Item should be deleted. item: #{item.inspect}")
+    item.recover_soft_deleted
+    assert(item.is_extant?, "Item should be extant")
+  end
+
+  def model_has_custom_reason_not_to_delete_defined(item)
+     item.class.private_method_defined?('reasons_not_to_delete?') or (item.reasons_not_to_delete != item.reasons_not_to_delete?)
+  end
+
+  def assert_errors_on_base(object)
+    assert(object.errors[:base],
+      "Should have Errors on base detected for object: #{object.inspect}"
+    )
+  end
+
+end
+
+ActiveSupport::TestCase.send(:include, ActsAsSoftDeleteByFieldAssertions)

data/lib/soft_delete_by_field.rb

@@ -0,0 +1,112 @@
+module ActiveRecord #:nodoc:
+  module Acts #:nodoc:
+    module SoftDeleteByField
+      DEFAULT_FIELD_NAME = :deleted_at
+
+      def self.included(base)
+        base.send :extend, ClassMethods
+      end
+
+      module ClassMethods
+
+        def soft_delete_by_field_name
+          @soft_delete_by_field_name
+        end
+
+        def acts_as_soft_delete_by_field(field_name = nil)
+          attr_accessor :reasons_not_to_delete
+          field_name ||= DEFAULT_FIELD_NAME
+          @soft_delete_by_field_name = field_name.to_sym
+          send :include, SoftDeleteByField::InstanceMethods
+          scope :extant, where(["#{(self.class.name.tableize + ".") if self.class.kind_of?(SoftDeleteByField)}#{field_name} IS NULL"])
+          scope :deleted, where(["#{(self.class.name.tableize + ".") if self.class.kind_of?(SoftDeleteByField)}#{field_name} IS NOT NULL"])
+        end
+  
+      end
+
+      module InstanceMethods
+
+
+        # Overwrite this method to add actions that are triggered before soft_delete operates.
+        def before_soft_delete
+
+        end
+
+        # Rename this 'delete' if you wish this functionality to replace the
+        # default delete behaviour.
+        def soft_delete
+          before_soft_delete
+          unless reasons_not_to_delete?
+            update_attribute(soft_delete_by_field_name, Time.now)
+            after_soft_delete
+            return 'deleted'
+          else
+            errors.add(:base, "Unable to delete. reasons_not_to_delete returns #{@reasons_not_to_delete || 'true'} for #{inspect}")
+          end
+        end
+
+        # Overwrite this method to add actions that are triggered after soft_delete operates.
+        def after_soft_delete
+
+        end
+
+        # Overwrite this method to add actions that are triggered before recover_soft_deleted operates.
+        def before_recover_soft_deleted
+
+        end
+
+        def recover_soft_deleted
+          before_recover_soft_deleted
+          update_attribute(soft_delete_by_field_name, nil)
+          after_recover_soft_deleted
+        end
+
+        # Overwrite this method to add actions that are triggered after recover_soft_deleted operates.
+        def after_recover_soft_deleted
+
+        end
+
+        def is_deleted?
+          send(soft_delete_by_field_name) != nil
+        end
+
+        def deleted?
+          is_deleted?
+        end
+
+        def is_extant?
+          !send(soft_delete_by_field_name)
+        end
+
+        def extant?
+          is_extant?
+        end
+
+        # You can either overwrite this method to add methods that prevent soft
+        # deletion, or set @reasons_not_to_delete to true. For example, set
+        # @reasons_not_to_delete = 'Component needs to be deleted first'
+        def reasons_not_to_delete?
+          @reasons_not_to_delete
+        end
+
+        def deleted_via_soft_delete_by_field_name_at
+          send(soft_delete_by_field_name)
+        end
+
+        private
+        def table_name_modifier
+          klass = self.class
+          if klass.kind_of?(SoftDeleteByField) and !klass.instance_of(SoftDeleteByField)
+            "#{klass.name.tableize}."
+          else
+            ""
+          end
+        end
+
+        def soft_delete_by_field_name
+          self.class.soft_delete_by_field_name
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification 
+name: acts_as_soft_delete_by_field
+version: !ruby/object:Gem::Version 
+  hash: 19
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  - 2
+  version: 1.0.2
+platform: ruby
+authors: 
+- Rob Nichols
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-08-05 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 3
+        - 0
+        - 0
+        version: 3.0.0
+  type: :runtime
+  version_requirements: *id001
+description: "Acts as Soft Delete by Field: Provides soft deletion for ActiveRecord models using a field to flag the datetime of deletion"
+email: rob@nicholshayes.co.uk
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README
+- Rakefile
+- lib/acts_as_soft_delete_by_field_assertions.rb
+- lib/acts_as_soft_delete_by_field.rb
+- lib/soft_delete_by_field.rb
+has_rdoc: true
+homepage: https://github.com/reggieb/acts_as_soft_delete_by_field
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Provides soft deletion for ActiveRecord models
+test_files: []
+