paper_trail 2.0.0 → 2.0.1

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    paper_trail (2.0.0)
+    paper_trail (2.0.1)
       rails (~> 3)
 
 GEM

data/README.md

@@ -7,7 +7,7 @@ PaperTrail lets you track changes to your models' data.  It's good for auditing
 
 * Stores every create, update and destroy.
 * Does not store updates which don't change anything.
-* Does not store updates which only change attributes you are ignoring.
+* Allows you to specify attributes (by inclusion or exclusion) which must change for a Version to be stored.
 * Allows you to get at every version, including the original, even once destroyed.
 * Allows you to get at every version even if the schema has since changed.
 * Allows you to get at the version as of a particular time.
@@ -26,7 +26,7 @@ PaperTrail lets you track changes to your models' data.  It's good for auditing
 
 ## Rails Version
 
-Works on Rails 3 and Rails 2.3.  The Rails 3 code is on the master branch and tagged v2.x.  The Rails 2.3 code is on the Rails 2 branch and tagged 1.x.
+Works on Rails 3 and Rails 2.3.  The Rails 3 code is on the `master` branch and tagged `v2.x`.  The Rails 2.3 code is on the `rails2` branch and tagged `v1.x`.
 
 
 ## API Summary
@@ -164,7 +164,7 @@ Here's a helpful table showing what PaperTrail stores:
 PaperTrail stores the values in the Model Before column.  Most other auditing/versioning plugins store the After column.
 
 
-## Ignoring changes to certain attributes
+## Choosing Attributes To Monitor
 
 You can ignore changes to certain attributes like this:
 
@@ -182,6 +182,23 @@ This means that changes to just the `title` or `rating` will not store another v
     >> a.versions.length                         # 2
     >> a.versions.last.reify.title               # 'My Title'
 
+Or, you can specify a list of all attributes you care about:
+
+    class Article < ActiveRecord::Base
+      has_paper_trail :only => [:title]
+    end
+
+This means that only changes to the `title` will save a version of the article:
+
+    >> a = Article.create
+    >> a.versions.length                         # 1
+    >> a.update_attributes :title => 'My Title'
+    >> a.versions.length                         # 2
+    >> a.update_attributes :content => 'Hello'
+    >> a.versions.length                         # 2
+
+Passing both `:ignore` and `:only` options will result in the article being saved if a changed attribute is included in `:only` but not in `:ignore`.
+
 
 ## Reverting And Undeleting A Model
 
@@ -494,29 +511,17 @@ Over time your `versions` table will grow to an unwieldy size.  Because each ver
 
 2. Generate a migration which will add a `versions` table to your database.
 
-    `rails generate paper_trail`
+    `bundle exec rails generate paper_trail`
 
 3. Run the migration.
 
-    `rake db:migrate`
+    `bundle exec rake db:migrate`
 
 4. Add `has_paper_trail` to the models you want to track.
 
 ### Rails 2
 
-1. Install PaperTrail as a gem via your `config/environment.rb`:
-
-    `config.gem 'paper_trail', :version => '~> 1'`
-
-2. Generate a migration which will add a `versions` table to your database.
-
-    `script/generate paper_trail`
-
-3. Run the migration.
-
-    `rake db:migrate`
-
-4. Add `has_paper_trail` to the models you want to track.
+Please see the `rails2` branch.
 
 
 ## Testing
@@ -547,7 +552,8 @@ Many thanks to:
 * Danny Trelogan
 * [Mikl Kurkov](http://github.com/mkurkov)
 * [Franco Catena](https://github.com/francocatena)
-* [Emmanuel](https://github.com/emmanuel)
+* [Emmanuel Gomez](https://github.com/emmanuel)
+* [Matthew MacLeod](https://github.com/mattmacleod)
 
 
 ## Inspirations
@@ -558,5 +564,5 @@ Many thanks to:
 
 ## Intellectual Property
 
-Copyright (c) 2009 Andy Stewart (boss@airbladesoftware.com).
+Copyright (c) 2011 Andy Stewart (boss@airbladesoftware.com).
 Released under the MIT licence.

data/lib/generators/paper_trail/install_generator.rb

@@ -0,0 +1,18 @@
+require 'rails/generators'
+require 'rails/generators/migration'
+require 'rails/generators/active_record/migration'
+
+module PaperTrail
+  class InstallGenerator < Rails::Generators::Base
+    include Rails::Generators::Migration
+    extend ActiveRecord::Generators::Migration
+
+    source_root File.expand_path('../templates', __FILE__)
+
+    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'
+    end
+  end
+end

data/lib/paper_trail/has_paper_trail.rb

@@ -12,6 +12,7 @@ module PaperTrail
       #
       # Options:
       # :ignore    an array of attributes for which a new `Version` will not be created if only they change.
+      # :only      inverse of `ignore` - a new `Version` will be created only for these attributes if supplied
       # :meta      a hash of extra data to store.  You must add a column to the `versions` table for each key.
       #            Values are objects or procs (which are called with `self`, i.e. the model with the paper
       #            trail).  See `PaperTrail::Controller.info_for_paper_trail` for how to store data from
@@ -25,8 +26,11 @@ module PaperTrail
         attr_accessor :version
 
         cattr_accessor :ignore
-        self.ignore = (options[:ignore] || []).map &:to_s
+        self.ignore = ([options[:ignore]].flatten.compact || []).map &:to_s
 
+        cattr_accessor :only
+        self.only = ([options[:only]].flatten.compact || []).map &:to_s
+        
         cattr_accessor :meta
         self.meta = options[:meta] || {}
 
@@ -68,11 +72,11 @@ module PaperTrail
       end
 
       # Returns the object (not a Version) as it was at the given timestamp.
-      def version_at(timestamp)
+      def version_at(timestamp, reify_options={})
         # Because a version stores how its object looked *before* the change,
         # we need to look for the first version created *after* the timestamp.
         version = versions.after(timestamp).first
-        version ? version.reify : self
+        version ? version.reify(reify_options) : self
       end
 
       # Returns the object (not a Version) as it was most recently.
@@ -147,6 +151,10 @@ module PaperTrail
       end
 
       def notably_changed
+        self.class.only.empty? ? changed_and_not_ignored : (changed_and_not_ignored & self.class.only)
+      end
+      
+      def changed_and_not_ignored
         changed - self.class.ignore
       end
 

data/lib/paper_trail/version.rb

@@ -99,7 +99,7 @@ class Version < ActiveRecord::Base
   end
 
   def index
-    sibling_versions.all(:select => :id, :order => "id ASC").map(&:id).index(self.id)
+    sibling_versions.select(:id).order("id ASC").map(&:id).index(self.id)
   end
 
   private

data/lib/paper_trail/version_number.rb

@@ -1,3 +1,3 @@
 module PaperTrail
-  VERSION = '2.0.0'
+  VERSION = '2.0.1'
 end

data/test/dummy/app/models/article.rb

@@ -1,5 +1,6 @@
 class Article < ActiveRecord::Base
-  has_paper_trail :ignore => [:title],
+  has_paper_trail :ignore => :title,
+                  :only => [:content],
                   :meta   => {:answer => 42,
                               :action => :action_data_provider_method,
                               :question => Proc.new { "31 + 11 = #{31 + 11}" },

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

@@ -49,6 +49,7 @@ class SetUpTestTables < ActiveRecord::Migration
     create_table :articles, :force => true do |t|
       t.string :title
       t.string :content
+      t.string :abstract
     end
 
     create_table :books, :force => true do |t|

data/test/dummy/db/schema.rb

@@ -15,6 +15,7 @@ ActiveRecord::Schema.define(:version => 20110208155312) do
   create_table "articles", :force => true do |t|
     t.string "title"
     t.string "content"
+    t.string "abstract"
   end
 
   create_table "authorships", :force => true do |t|

data/test/unit/model_test.rb

@@ -10,10 +10,21 @@ class HasPaperTrailModelTest < ActiveSupport::TestCase
       should_not_change('the number of versions') { Version.count }
     end
 
-    context 'which updates an ignored column and a non-ignored column' do
+    context 'which updates an ignored column and a selected column' do
       setup { @article.update_attributes :title => 'My first title', :content => 'Some text here.' }
       should_change('the number of versions', :by => 1) { Version.count }
     end
+    
+    context 'which updates a selected column' do
+      setup { @article.update_attributes :content => 'Some text here.' }
+      should_change('the number of versions', :by => 1) { Version.count }
+    end
+
+    context 'which updates a non-ignored and non-selected column' do
+      setup { @article.update_attributes :abstract => 'Other abstract'}
+      should_not_change('the number of versions') { Version.count }
+    end
+    
   end
 
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: paper_trail
 version: !ruby/object:Gem::Version 
-  hash: 15
+  hash: 13
   prerelease: false
   segments: 
   - 2
   - 0
-  - 0
-  version: 2.0.0
+  - 1
+  version: 2.0.1
 platform: ruby
 authors: 
 - Andy Stewart
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-02-08 00:00:00 +00:00
+date: 2011-02-25 00:00:00 +00:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -95,7 +95,7 @@ files:
 - README.md
 - Rakefile
 - lib/generators/paper_trail/USAGE
-- lib/generators/paper_trail/paper_trail_generator.rb
+- lib/generators/paper_trail/install_generator.rb
 - lib/generators/paper_trail/templates/create_versions.rb
 - lib/paper_trail.rb
 - lib/paper_trail/config.rb

data/lib/generators/paper_trail/paper_trail_generator.rb

@@ -1,24 +0,0 @@
-require 'rails/generators/named_base'
-require 'rails/generators/migration'
-
-class PaperTrailGenerator < Rails::Generators::NamedBase
-  include Rails::Generators::Migration
-
-  desc "Generates (but does not run) a migration to add a versions table."
-  source_root File.expand_path('../templates', __FILE__)
-  argument :name, :type => :string, :default => "create_versions"
-
-  # Implement the required interface for Rails::Generators::Migration.
-  # taken from http://github.com/rails/rails/blob/master/activerecord/lib/generators/active_record.rb
-  def self.next_migration_number(dirname)
-    if ActiveRecord::Base.timestamped_migrations
-      Time.now.utc.strftime("%Y%m%d%H%M%S")
-    else
-      "%.3d" % (current_migration_number(dirname) + 1)
-    end
-  end
-
-  def create_migration_file
-    migration_template 'create_versions.rb', 'db/migrate/create_versions.rb'
-  end
-end