paper_trail 2.2.6 → 2.2.7

data/.gitignore

@@ -7,3 +7,4 @@ pkg/*
 *.gem
 .bundle
 Gemfile.lock
+vendor/*

data/README.md

@@ -453,11 +453,20 @@ Remember to add those extra columns to your `versions` table ;)
 
 ## Diffing Versions
 
-When you're storing every version of an object, as PaperTrail lets you do, you're almost certainly going to want to diff those versions against each other.  However I haven't built a diff method into PaperTrail because I think diffing is best left to dedicated libraries, and also it's hard to come up with a diff method to suit all the use cases.
+There are two scenarios: diffing adjacent versions and diffing non-adjacent versions.
 
-You might be surprised that PaperTrail doesn't use diffs internally anyway.  When I designed PaperTrail I wanted simplicity and robustness so I decided to make each version of an object self-contained.  A version stores all of its object's data, not a diff from the previous version.
+The best way to diff adjacent versions is to get PaperTrail to do it for you.  If you add an `object_changes` text column to your `versions` table, either at installation time with the `--with-changes` option or manually, PaperTrail will store the `changes` diff in each `update` version.  You can use the `version.changeset` method to retrieve it.  For example:
 
-So instead here are some specialised diffing libraries which you can use on top of PaperTrail.
+    >> widget = Widget.create :name => 'Bob'
+    >> widget.versions.last.changeset                # nil
+    >> widget.update_attributes :name => 'Robert'
+    >> widget.versions.last.changeset                # {'name' => ['Bob', 'Robert']}
+
+Note PaperTrail only stores the changes for updates; there's no point storing them for created or destroyed objects.
+
+Please be aware that PaperTrail doesn't use diffs internally.  When I designed PaperTrail I wanted simplicity and robustness so I decided to make each version of an object self-contained.  A version stores all of its object's data, not a diff from the previous version.  This means you can delete any version without affecting any other.
+
+To diff non-adjacent versions you'll have to write your own code.  These libraries may help:
 
 For diffing two strings:
 
@@ -604,6 +613,7 @@ Many thanks to:
 * [Burke Libbey](https://github.com/burke)
 * [6twenty](https://github.com/6twenty)
 * [nir0](https://github.com/nir0)
+* [Eduard Tsech](https://github.com/edtsech)
 
 
 ## Inspirations

data/lib/generators/paper_trail/install_generator.rb

@@ -8,11 +8,13 @@ module PaperTrail
     extend ActiveRecord::Generators::Migration
 
     source_root File.expand_path('../templates', __FILE__)
+    class_option :with_changes, :type => :boolean, :default => false, :desc => "Store changeset (diff) with each version"
 
     desc 'Generates (but does not run) a migration to add a versions table.'
 
     def create_migration_file
       migration_template 'create_versions.rb', 'db/migrate/create_versions.rb'
+      migration_template 'add_object_changes_column_to_versions.rb', 'db/migrate/add_object_changes_column_to_versions.rb' if options.with_changes?
     end
   end
 end

data/lib/generators/paper_trail/templates/add_object_changes_column_to_versions.rb

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

data/lib/paper_trail/has_paper_trail.rb

@@ -109,9 +109,13 @@ module PaperTrail
 
       def record_update
         if switched_on? && changed_notably?
-          versions.build merge_metadata(:event     => 'update',
-                                        :object    => object_to_string(item_before_change),
-                                        :whodunnit => PaperTrail.whodunnit)
+          data = {
+            :event     => 'update',
+            :object    => object_to_string(item_before_change),
+            :whodunnit => PaperTrail.whodunnit
+          }
+          data[:object_changes] = self.changes.to_yaml if Version.method_defined? :object_changes
+          versions.build merge_metadata(data)
         end
       end
 

data/lib/paper_trail/version.rb

@@ -79,6 +79,11 @@ class Version < ActiveRecord::Base
     end
   end
 
+  # Returns what changed in this version of the item.  Cf. `ActiveModel::Dirty#changes`.
+  def changeset
+    YAML::load(object_changes) if Version.method_defined?(:object_changes) && object_changes
+  end
+
   # Returns who put the item into the state stored in this version.
   def originator
     previous.try :whodunnit

data/lib/paper_trail/version_number.rb

@@ -1,3 +1,3 @@
 module PaperTrail
-  VERSION = '2.2.6'
+  VERSION = '2.2.7'
 end

data/test/dummy/db/migrate/20110208155312_set_up_test_tables.rb

@@ -21,6 +21,7 @@ class SetUpTestTables < ActiveRecord::Migration
       t.string   :event,     :null => false
       t.string   :whodunnit
       t.text     :object
+      t.text     :object_changes
       t.datetime :created_at
 
       # Metadata columns.
@@ -34,7 +35,7 @@ class SetUpTestTables < ActiveRecord::Migration
       t.string :user_agent
     end
     add_index :versions, [:item_type, :item_id]
-    
+
     create_table :post_versions, :force => true do |t|
       t.string   :item_type, :null => false
       t.integer  :item_id,   :null => false

data/test/test_helper.rb

@@ -47,3 +47,11 @@ def change_schema
   end
   ActiveRecord::Migration.verbose = true
 end
+
+def remove_object_changes_column
+  ActiveRecord::Migration.verbose = false
+  ActiveRecord::Schema.define do
+    remove_column :versions, :object_changes
+  end
+  ActiveRecord::Migration.verbose = true
+end

data/test/unit/model_test.rb

@@ -60,6 +60,9 @@ class HasPaperTrailModelTest < ActiveSupport::TestCase
         assert @widget.live?
       end
 
+      should 'should not have changes' do
+        assert_nil @widget.versions.last.changeset
+      end
 
       context 'and then updated without any changes' do
         setup { @widget.save }
@@ -97,6 +100,17 @@ class HasPaperTrailModelTest < ActiveSupport::TestCase
           assert @widget.versions.map(&:reify).compact.all? { |w| !w.live? }
         end
 
+        should 'have stored changes' do
+          assert_equal ({'name' => ['Henry', 'Harry']}), YAML::load(@widget.versions.last.object_changes)
+          assert_equal ({'name' => ['Henry', 'Harry']}), @widget.versions.last.changeset
+        end
+
+        should 'not have stored changes if object_changes column doesn\'t exist' do
+          remove_object_changes_column
+          Version.reset_column_information
+          assert_nil @widget.versions.last.changeset
+        end
+
         if defined?(ActiveRecord::IdentityMap) && ActiveRecord::IdentityMap.respond_to?(:without)
           should 'not clobber the IdentityMap when reifying' do
             module ActiveRecord::IdentityMap
@@ -118,7 +132,7 @@ class HasPaperTrailModelTest < ActiveSupport::TestCase
           setup do
             @wotsit = @widget.create_wotsit :name => 'John'
           end
-          
+
           should 'not copy the has_one association by default when reifying' do
             reified_widget = @widget.versions.last.reify
             assert_equal @wotsit, reified_widget.wotsit  # association hasn't been affected by reifying

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: paper_trail
 version: !ruby/object:Gem::Version 
-  hash: 11
+  hash: 9
   prerelease: false
   segments: 
   - 2
   - 2
-  - 6
-  version: 2.2.6
+  - 7
+  version: 2.2.7
 platform: ruby
 authors: 
 - Andy Stewart
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-07-11 00:00:00 +01:00
+date: 2011-07-13 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -109,6 +109,7 @@ files:
 - Rakefile
 - lib/generators/paper_trail/USAGE
 - lib/generators/paper_trail/install_generator.rb
+- lib/generators/paper_trail/templates/add_object_changes_column_to_versions.rb
 - lib/generators/paper_trail/templates/create_versions.rb
 - lib/paper_trail.rb
 - lib/paper_trail/config.rb