paper_trail 1.6.2 → 1.6.3

data/README.md

@@ -29,6 +29,76 @@ PaperTrail lets you track changes to your models' data.  It's good for auditing
 Works on Rails 3 and Rails 2.3.  Probably works on Rails 2.2 and 2.1.
 
 
+## API Summary
+
+When you declare `has_paper_trail` in your model, you get these methods:
+
+    class Widget < ActiveRecord::Base
+      has_paper_trail   # you can pass various options here
+    end
+
+    # Returns this widget's versions.
+    widget.versions
+
+    # Return the version this widget was reified from, or nil if it is live.
+    widget.version
+
+    # Returns true if this widget is the current, live one; or false if it is from a previous version.
+    widget.live?
+
+    # Returns who put the widget into its current state.
+    widget.originator
+
+    # Returns the widget (not a version) as it looked at the given timestamp.
+    widget.version_at(timestamp)
+
+    # Returns the widget (not a version) as it was most recently.
+    widget.previous_version
+
+    # Returns the widget (not a version) as it became next.
+    widget.next_version
+
+    # Turn PaperTrail off for all widgets.
+    Widget.paper_trail_off
+
+    # Turn PaperTrail on for all widgets.
+    Widget.paper_trail_on
+
+And a `Version` instance has these methods:
+
+    # Returns the item restored from this version.
+    version.reify(options = {})
+
+    # Returns who put the item into the state stored in this version.
+    version.originator
+
+    # Returns who changed the item from the state it had in this version.
+    version.terminator
+    version.whodunnit
+
+    # Returns the next version.
+    version.next
+
+    # Returns the previous version.
+    version.previous
+
+    # Returns the index of this version in all the versions.
+    version.index
+
+    # Returns the event that caused this version (create|update|destroy).
+    version.event
+
+In your controllers you can override these methods:
+
+    # Returns the user who is responsible for any changes that occur.
+    # Defaults to current_user.
+    user_for_paper_trail
+
+    # Returns any information about the controller or request that you want
+    # PaperTrail to store alongside any changes that occur.
+    info_for_paper_trail
+
+
 ## Basic Usage
 
 PaperTrail is simple to use.  Just add 15 characters to a model to get a paper trail of every `create`, `update`, and `destroy`.
@@ -289,7 +359,20 @@ But none of these will:
     >> @book.author_ids = [@solzhenistyn.id, @dostoyevsky.id]
     >> @book.authors = []
 
-Having said that, you can probably (I haven't tested it myself) get the first one (`@book.authors.delete @tolstoy`) working with this [monkey patch](http://stackoverflow.com/questions/2381033/how-to-create-a-full-audit-log-in-rails-for-every-table/2381411#2381411).  Many thanks to Danny Trelogan for pointing it out.
+Having said that, you can apparently get all these working (I haven't tested it myself) with this [monkey patch](http://stackoverflow.com/questions/2381033/how-to-create-a-full-audit-log-in-rails-for-every-table/2381411#2381411):
+
+    # In config/initializers/core_extensions.rb or lib/core_extensions.rb
+    ActiveRecord::Associations::HasManyThroughAssociation.class_eval do 
+      def delete_records(records)
+        klass = @reflection.through_reflection.klass
+        records.each do |associate|
+          klass.destroy_all(construct_join_attributes(associate))
+        end
+      end
+    end
+
+The difference is the call to `destroy_all` instead of `delete_all` in [the original](http://github.com/rails/rails/blob/master/activerecord/lib/active_record/associations/has_many_through_association.rb#L76-81).
+    
 
 There may be a way to store authorship versions, probably using association callbacks, no matter how the collection is manipulated but I haven't found it yet.  Let me know if you do.
 
@@ -454,6 +537,8 @@ Many thanks to:
 * [Phan Le](http://github.com/revo)
 * [jdrucza](http://github.com/jdrucza)
 * [conickal](http://github.com/conickal)
+* [Thibaud Guillaume-Gentil](http://github.com/thibaudgg)
+* Danny Trelogan
 
 
 ## Inspirations

data/lib/paper_trail/has_paper_trail.rb

@@ -56,28 +56,6 @@ module PaperTrail
     # Wrap the following methods in a module so we can include them only in the
     # ActiveRecord models that declare `has_paper_trail`.
     module InstanceMethods
-      def record_create
-        if switched_on?
-          versions.create merge_metadata(:event => 'create', :whodunnit => PaperTrail.whodunnit)
-        end
-      end
-
-      def record_update
-        if switched_on? && changed_and_we_care?
-          versions.build merge_metadata(:event     => 'update',
-                                        :object    => object_to_string(item_before_change),
-                                        :whodunnit => PaperTrail.whodunnit)
-        end
-      end
-
-      def record_destroy
-        if switched_on?
-          versions.create merge_metadata(:event     => 'destroy',
-                                         :object    => object_to_string(item_before_change),
-                                         :whodunnit => PaperTrail.whodunnit)
-        end
-      end
-
       # Returns true if this instance is the current, live one;
       # returns false if this instance came from a previous version.
       def live?
@@ -113,6 +91,28 @@ module PaperTrail
 
       private
 
+      def record_create
+        if switched_on?
+          versions.create merge_metadata(:event => 'create', :whodunnit => PaperTrail.whodunnit)
+        end
+      end
+
+      def record_update
+        if switched_on? && changed_and_we_care?
+          versions.build merge_metadata(:event     => 'update',
+                                        :object    => object_to_string(item_before_change),
+                                        :whodunnit => PaperTrail.whodunnit)
+        end
+      end
+
+      def record_destroy
+        if switched_on? and not new_record?
+          versions.create merge_metadata(:event     => 'destroy',
+                                         :object    => object_to_string(item_before_change),
+                                         :whodunnit => PaperTrail.whodunnit)
+        end
+      end
+
       def merge_metadata(data)
         # First we merge the model-level metadata in `meta`.
         meta.each do |k,v|

data/lib/paper_trail/version_number.rb

@@ -1,3 +1,3 @@
 module PaperTrail
-  VERSION = '1.6.2'
+  VERSION = '1.6.3'
 end

data/test/paper_trail_model_test.rb

@@ -769,6 +769,17 @@ class HasPaperTrailModelTest < Test::Unit::TestCase
   end
 
 
+  context 'An unsaved record' do
+    setup do
+      @widget = Widget.new
+      @widget.destroy
+    end
+    should 'not have a version created on destroy' do
+      assert @widget.versions.empty?
+    end
+  end
+
+
   private
 
   # Updates `model`'s last version so it looks like the version was

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: paper_trail
 version: !ruby/object:Gem::Version 
-  hash: 11
+  hash: 9
   prerelease: false
   segments: 
   - 1
   - 6
-  - 2
-  version: 1.6.2
+  - 3
+  version: 1.6.3
 platform: ruby
 authors: 
 - Andy Stewart
@@ -20,9 +20,8 @@ default_executable:
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: bundler
-  type: :development
   prerelease: false
-  version_requirements: &id001 !ruby/object:Gem::Requirement 
+  requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -32,12 +31,12 @@ dependencies:
         - 1
         - 0
         version: "1.0"
-  requirement: *id001
+  type: :development
+  version_requirements: *id001
 - !ruby/object:Gem::Dependency 
   name: rake
-  type: :development
   prerelease: false
-  version_requirements: &id002 !ruby/object:Gem::Requirement 
+  requirement: &id002 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - "="
@@ -48,12 +47,12 @@ dependencies:
         - 8
         - 7
         version: 0.8.7
-  requirement: *id002
+  type: :development
+  version_requirements: *id002
 - !ruby/object:Gem::Dependency 
   name: shoulda
-  type: :development
   prerelease: false
-  version_requirements: &id003 !ruby/object:Gem::Requirement 
+  requirement: &id003 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - "="
@@ -64,12 +63,12 @@ dependencies:
         - 10
         - 3
         version: 2.10.3
-  requirement: *id003
+  type: :development
+  version_requirements: *id003
 - !ruby/object:Gem::Dependency 
   name: activesupport
-  type: :development
   prerelease: false
-  version_requirements: &id004 !ruby/object:Gem::Requirement 
+  requirement: &id004 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -79,12 +78,12 @@ dependencies:
         - 2
         - 3
         version: "2.3"
-  requirement: *id004
+  type: :development
+  version_requirements: *id004
 - !ruby/object:Gem::Dependency 
   name: sqlite3-ruby
-  type: :development
   prerelease: false
-  version_requirements: &id005 !ruby/object:Gem::Requirement 
+  requirement: &id005 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -94,12 +93,12 @@ dependencies:
         - 1
         - 2
         version: "1.2"
-  requirement: *id005
+  type: :development
+  version_requirements: *id005
 - !ruby/object:Gem::Dependency 
   name: activerecord
-  type: :runtime
   prerelease: false
-  version_requirements: &id006 !ruby/object:Gem::Requirement 
+  requirement: &id006 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -109,12 +108,12 @@ dependencies:
         - 2
         - 3
         version: "2.3"
-  requirement: *id006
+  type: :runtime
+  version_requirements: *id006
 - !ruby/object:Gem::Dependency 
   name: actionpack
-  type: :runtime
   prerelease: false
-  version_requirements: &id007 !ruby/object:Gem::Requirement 
+  requirement: &id007 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -124,7 +123,8 @@ dependencies:
         - 2
         - 3
         version: "2.3"
-  requirement: *id007
+  type: :runtime
+  version_requirements: *id007
 description: Track changes to your models' data.  Good for auditing or versioning.
 email: boss@airbladesoftware.com
 executables: []