mongoid-history 0.3.3 → 0.4.0

data/CHANGELOG.md

@@ -1,4 +1,22 @@
-0.3.3 (1/4/2013)
+0.4.0 (6/12/2013)
+-----------------
+
+* Add Mongoid::History.disable and Mongoid::History.enabled? methods for global tracking disablement - [@johnnyshields](https://github.com/johnnyshields)
+* Add `:changes_method` that optionally overrides which method to call to collect changes - [@joelnordel](https://github.com/joelnordell).
+* [API Change] The `:destroy` action now stores trackers in the format `original=value, modified=nil` (previously it was the reverse) - [@johnnyshields](https://github.com/johnnyshields)
+* Support for polymorphic embedded classes - [@tstepp](https://github.com/tstepp)
+* Support for Mongoid field aliases, e.g. `field :n, as: :name` - [@johnnyshields](https://github.com/johnnyshields)
+* Support for Mongoid embedded aliases, e.g. `embeds_many :comments, store_as: :coms` - [@johnnyshields](https://github.com/johnnyshields)
+* Add `#tracked_changes` and `#tracked_edits` methods to `Tracker` class for nicer change summaries - [@johnnyshields](https://github.com/johnnyshields) and [@tstepp](https://github.com/tstepp)
+* Refactored and exposed `#trackable_parent_class` in `Tracker`, which returns the class of the trackable regardless of whether the trackable itself has been destroyed - [@johnnyshields](https://github.com/johnnyshields)
+* Add class-level `#tracked_field?` and `#tracked_fields` methods; refactor logic to determine whether a field is tracked - [@johnnyshields](https://github.com/johnnyshields)
+* Fix bug in Trackable#track_update where `return` condition at beginning of method caused a short-circuit where memoization would not be cleared properly. - [@johnnyshields](https://github.com/johnnyshields)
+* Tests: Added spec for nested embedded documents - [@matekb](https://github.com/matekb)
+* Tests: Test run time cut in half (~2.5s versus ~5s) by using `#let` helper and removing class initialization before each test - [@johnnyshields](https://github.com/johnnyshields)
+* Tests: Remove `database_cleaner` gem in favor of `Mongoid.purge!` - [@johnnyshields](https://github.com/johnnyshields)
+* Tests: Remove dependency on non-committed file `mongoid.yml` and hardcode collection to `mongoid_history_test` - [@johnnyshields](https://github.com/johnnyshields)
+
+0.3.3 (4/1/2013)
 ----------------
 
 * [#42](https://github.com/aq1018/mongoid-history/issues/42) Fix: corrected creation of association chain when using nested embedded documents - [@matekb](https://github.com/matekb).

data/Gemfile

@@ -5,9 +5,8 @@ gem "mongoid", "~> 3.0"
 gem "activesupport"
 
 group :test do
-  gem "rspec", "~> 2.11.0"
+  gem "rspec", ">= 2.11.0"
   gem "yard"
   gem "bundler", ">= 1.0.0"
   gem "jeweler"
-  gem "database_cleaner", ">= 0.8.0"
 end

data/README.md

@@ -2,6 +2,7 @@ mongoid-history
 ===============
 
 [![Build Status](https://secure.travis-ci.org/aq1018/mongoid-history.png?branch=master)](http://travis-ci.org/aq1018/mongoid-history)
+[![Code Climate](https://codeclimate.com/github/aq1018/mongoid-history.png)](https://codeclimate.com/github/aq1018/mongoid-history)
 
 Mongoid-history tracks historical changes for any document, including embedded ones. It achieves this by storing all history tracks in a single collection that you define. Embedded documents are referenced by storing an association path, which is an array of `document_name` and `document_id` fields starting from the top most parent document and down to the embedded document that should track history.
 
@@ -10,7 +11,7 @@ This gem also implements multi-user undo, which allows users to undo any history
 Stable Release
 --------------
 
-You're reading the documentation the 0.3.x release that supports Mongoid 3.x. For 2.x compatible mongoid-history, please use a 0.2.x version from the [2.x-stable branch](https://github.com/aq1018/mongoid-history/tree/2.4-stable).
+You're reading the documentation the 0.4.x release that supports Mongoid 3.x. For 2.x compatible mongoid-history, please use a 0.2.x version from the [2.x-stable branch](https://github.com/aq1018/mongoid-history/tree/2.4-stable).
 
 Install
 -------
@@ -160,7 +161,128 @@ post.undo! user
 Comment.disable_tracking do
   comment.update_attributes(:title => "Test 3")
 end
+
+# globally disable all history tracking
+Mongoid::History.disable do
+  comment.update_attributes(:title => "Test 3")
+  user.update_attributes(:name => "Eddie Van Halen")
+end
+```
+
+**Retrieving the list of tracked fields**
+
+```ruby
+class Book
+  ...
+  field             :title
+  field             :author
+  field             :price
+  track_history     :on => [:title, :price]
+end
+
+Book.tracked_fields           #=> ["title", "price"]
+Book.tracked_field?(:title)   #=> true
+Book.tracked_field?(:author)  #=> false
 ```
+
+**Displaying history trackers as an audit trail**
+
+In your Controller:
+
+```ruby
+# Fetch history trackers
+@trackers = HistoryTracker.limit(25)
+
+# get change set for the first tracker
+@changes = @trackers.first.tracked_changes
+  #=> {field: {to: val1, from: val2}}
+
+# get edit set for the first tracker
+@edits = @trackers.first.tracked_changes
+  #=> { add: {field: val},
+  #     remove: {field: val},
+  #     modify: { to: val1, from: val2 },
+  #     array: { add: [val2], remove: [val1] } }
+```
+
+In your View, you might do something like (example in HAML format):
+
+```haml
+%ul.changes
+  - (@edits[:add]||[]).each do |k,v|
+    %li.remove Added field #{k} value #{v}
+
+  - (@edits[:modify]||[]).each do |k,v|
+    %li.modify Changed field #{k} from #{v[:from]} to #{v[:to]}
+
+  - (@edits[:array]||[]).each do |k,v|
+    %li.modify
+      - if v[:remove].nil?
+        Changed field #{k} by adding #{v[:add]}
+      - elsif v[:add].nil?
+        Changed field #{k} by removing #{v[:remove]}
+      - else
+        Changed field #{k} by adding #{v[:add]} and removing #{v[:remove]}
+
+  - (@edits[:remove]||[]).each do |k,v|
+    %li.remove Removed field #{k} (was previously #{v})
+```
+
+**Using an alternate changes method**
+
+Sometimes you may wish to provide an alternate method for determining which changes should be tracked.  For example, if you are using embedded documents
+and nested attributes, you may wish to write your own changes method that includes changes from the embedded documents.
+
+Mongoid::History provides an option named `:changes_method` which allows you to do this.  It defaults to `:changes`, which is the standard changes method.
+
+Example:
+
+```ruby
+class Foo
+  include Mongoid::Document
+  include Mongoid::Timestamps
+  include Mongoid::History::Trackable
+
+  field      :bar
+  embeds_one :baz
+  accepts_nested_attributes_for :baz
+
+  # use changes_with_baz to include baz's changes in this document's
+  # history.
+  track_history     :changes_method => :changes_with_baz
+
+  def changes_with_baz
+    if baz.changed?
+      changes.merge( :baz => summarized_changes(baz) )
+    else
+      changes
+    end
+  end
+
+  private
+  # This method takes the changes from an embedded doc and formats them
+  # in a summarized way, similar to how the embedded doc appears in the
+  # parent document's attributes
+  def summarized_changes obj
+    obj.changes.keys.map do |field|
+      next unless obj.respond_to?("#{field}_change")
+      [ { field => obj.send("#{field}_change")[0] },
+        { field => obj.send("#{field}_change")[1] } ]
+    end.compact.transpose.map do |fields|
+      fields.inject({}) {|map,f| map.merge(f)}
+    end
+  end
+end
+
+class Baz
+  include Mongoid::Document
+  include Mongoid::Timestamps
+
+  embedded_in :foo
+  field :value
+end
+```
+
 For more examples, check out [spec/integration/integration_spec.rb](https://github.com/aq1018/mongoid-history/blob/master/spec/integration/integration_spec.rb).
 
 Contributing to mongoid-history

data/VERSION

@@ -1 +1 @@
-0.3.3
+0.4.0

data/lib/mongoid/history.rb

@@ -1,5 +1,7 @@
 module Mongoid
   module History
+    GLOBAL_TRACK_HISTORY_FLAG = "mongoid_history_trackable_enabled"
+
     mattr_accessor :tracker_class_name
     mattr_accessor :trackable_class_options
     mattr_accessor :modifier_class_name
@@ -9,5 +11,17 @@ module Mongoid
       @tracker_class ||= tracker_class_name.to_s.classify.constantize
     end
 
+    def self.disable(&block)
+      begin
+        Thread.current[GLOBAL_TRACK_HISTORY_FLAG] = false
+        yield
+      ensure
+        Thread.current[GLOBAL_TRACK_HISTORY_FLAG] = true
+      end
+    end
+
+    def self.enabled?
+      Thread.current[GLOBAL_TRACK_HISTORY_FLAG] != false
+    end
   end
 end

data/lib/mongoid/history/trackable.rb

@@ -10,6 +10,7 @@ module Mongoid::History
           :except         =>  [:created_at, :updated_at],
           :modifier_field =>  :modifier,
           :version_field  =>  :version,
+          :changes_method =>  :changes,
           :scope          =>  scope_name,
           :track_create   =>  false,
           :track_update   =>  true,
@@ -18,19 +19,14 @@ module Mongoid::History
 
         options = default_options.merge(options)
 
-        # normalize except fields
-        # manually ensure _id, id, version will not be tracked in history
+        # normalize :except fields to an array of database field strings
         options[:except] = [options[:except]] unless options[:except].is_a? Array
-        options[:except] << options[:version_field]
-        options[:except] << "#{options[:modifier_field]}_id".to_sym
-        options[:except] += [:_id, :id]
-        options[:except] = options[:except].map(&:to_s).flatten.compact.uniq
-        options[:except].map(&:to_s)
+        options[:except] = options[:except].map{|field| database_field_name(field)}.compact.uniq
 
-        # normalize fields to track to either :all or an array of strings
+        # normalize :on fields to either :all or an array of database field strings
         if options[:on] != :all
           options[:on] = [options[:on]] unless options[:on].is_a? Array
-          options[:on] = options[:on].map(&:to_s).flatten.uniq
+          options[:on] = options[:on].map{|field| database_field_name(field)}.compact.uniq
         end
 
         field options[:version_field].to_sym, :type => Integer
@@ -54,8 +50,7 @@ module Mongoid::History
       end
 
       def track_history?
-        enabled = Thread.current[track_history_flag]
-        enabled.nil? ? true : enabled
+        Mongoid::History.enabled? && Thread.current[track_history_flag] != false
       end
 
       def disable_tracking(&block)
@@ -101,6 +96,14 @@ module Mongoid::History
         save!
       end
 
+      def get_embedded(name)
+        self.send(self.class.embedded_alias(name))
+      end
+
+      def create_embedded(name, value)
+        self.send("create_#{self.class.embedded_alias(name)}!", value)
+      end
+
     private
       def get_versions_criteria(options_or_version)
         if options_or_version.is_a? Hash
@@ -124,10 +127,6 @@ module Mongoid::History
         versions.desc(:version)
       end
 
-      def should_track_update?
-        track_history? && !modified_attributes_for_update.blank?
-      end
-
       def traverse_association_chain(node=self)
         list = node._parent ? traverse_association_chain(node._parent) : []
         list << association_hash(node)
@@ -141,7 +140,7 @@ module Mongoid::History
         # the child to parent (embedded_in, belongs_to) relation will be defined
         if node._parent
           meta = node._parent.relations.values.select do |relation|
-            relation.class_name == node.class.to_s
+            relation.class_name == node.metadata.class_name.to_s
           end.first
         end
 
@@ -151,81 +150,68 @@ module Mongoid::History
         ActiveSupport::OrderedHash['name', name, 'id', node.id]
       end
 
-      def modified_attributes_for_update
-        @modified_attributes_for_update ||= if history_trackable_options[:on] == :all
-          changes.reject do |k, v|
-            history_trackable_options[:except].include?(k)
-          end
-        else
-          changes.reject do |k, v|
-            !history_trackable_options[:on].include?(k)
-          end
-
+      # Returns a Hash of field name to pairs of original and modified values
+      # for each tracked field for a given action.
+      #
+      # @param [ String | Symbol ] action The modification action (:create, :update, :destroy)
+      #
+      # @return [ Hash<String, Array<Object>> ] the pairs of original and modified
+      #   values for each field
+      def modified_attributes_for_action(action)
+        case action.to_sym
+          when :destroy then modified_attributes_for_destroy
+          when :create then modified_attributes_for_create
+          else modified_attributes_for_update
         end
       end
 
+      def modified_attributes_for_update
+        @modified_attributes_for_update ||= self.send(history_trackable_options[:changes_method]).select{|k, v| self.class.tracked_field?(k, :update)}
+      end
+
       def modified_attributes_for_create
-        @modified_attributes_for_create ||= attributes.inject({}) do |h, pair|
-          k,v =  pair
+        @modified_attributes_for_create ||= attributes.inject({}) do |h,(k,v)|
           h[k] = [nil, v]
           h
-        end.reject do |k, v|
-          history_trackable_options[:except].include?(k)
-        end
+        end.select{|k, v| self.class.tracked_field?(k, :create)}
       end
 
       def modified_attributes_for_destroy
-        @modified_attributes_for_destroy ||= attributes.inject({}) do |h, pair|
-          k,v =  pair
-          h[k] = [nil, v]
+        @modified_attributes_for_destroy ||= attributes.inject({}) do |h,(k,v)|
+          h[k] = [v, nil]
           h
-        end
+        end.select{|k, v| self.class.tracked_field?(k, :destroy)}
       end
 
-      def history_tracker_attributes(method)
+      def history_tracker_attributes(action)
         return @history_tracker_attributes if @history_tracker_attributes
 
         @history_tracker_attributes = {
           :association_chain  => traverse_association_chain,
           :scope              => history_trackable_options[:scope],
-          :modifier        => send(history_trackable_options[:modifier_field])
+          :modifier           => send(history_trackable_options[:modifier_field])
         }
 
-        original, modified = transform_changes(case method
-          when :destroy then modified_attributes_for_destroy
-          when :create then modified_attributes_for_create
-          else modified_attributes_for_update
-        end)
+        original, modified = transform_changes(modified_attributes_for_action(action))
 
         @history_tracker_attributes[:original] = original
         @history_tracker_attributes[:modified] = modified
         @history_tracker_attributes
       end
 
-      def track_update
-        return unless should_track_update?
-        current_version = (self.send(history_trackable_options[:version_field]) || 0 ) + 1
-        self.send("#{history_trackable_options[:version_field]}=", current_version)
-        Mongoid::History.tracker_class.create!(history_tracker_attributes(:update).merge(:version => current_version, :action => "update", :trackable => self))
-        clear_memoization
+      def track_create
+        track_history_for_action(:create)
       end
 
-      def track_create
-        return unless track_history?
-        current_version = (self.send(history_trackable_options[:version_field]) || 0 ) + 1
-        self.send("#{history_trackable_options[:version_field]}=", current_version)
-        Mongoid::History.tracker_class.create!(history_tracker_attributes(:create).merge(:version => current_version, :action => "create", :trackable => self))
-        clear_memoization
+      def track_update
+        track_history_for_action(:update)
       end
 
       def track_destroy
-        return unless track_history?
-        current_version = (self.send(history_trackable_options[:version_field]) || 0 ) + 1
-        Mongoid::History.tracker_class.create!(history_tracker_attributes(:destroy).merge(:version => current_version, :action => "destroy", :trackable => self))
-        clear_memoization
+        track_history_for_action(:destroy)
       end
 
-      def clear_memoization
+      def clear_trackable_memoization
         @history_tracker_attributes =  nil
         @modified_attributes_for_create = nil
         @modified_attributes_for_update = nil
@@ -244,12 +230,109 @@ module Mongoid::History
         [ original, modified ]
       end
 
+      protected
+
+      def track_history_for_action?(action)
+        track_history? && !(action.to_sym == :update && modified_attributes_for_update.blank?)
+      end
+
+      def track_history_for_action(action)
+        if track_history_for_action?(action)
+          current_version = (self.send(history_trackable_options[:version_field]) || 0 ) + 1
+          self.send("#{history_trackable_options[:version_field]}=", current_version)
+          Mongoid::History.tracker_class.create!(history_tracker_attributes(action.to_sym).merge(version: current_version, action: action.to_s, trackable: self))
+        end
+        clear_trackable_memoization
+      end
     end
 
     module SingletonMethods
+
+      # Whether or not the field should be tracked.
+      #
+      # @param [ String | Symbol ] field The name or alias of the field
+      # @param [ String | Symbol ] action The optional action name (:create, :update, or :destroy)
+      #
+      # @return [ Boolean ] whether or not the field is tracked for the given action
+      def tracked_field?(field, action = :update)
+        tracked_fields_for_action(action).include? database_field_name(field)
+      end
+
+      # Retrieves the list of tracked fields for a given action.
+      #
+      # @param [ String | Symbol ] action The action name (:create, :update, or :destroy)
+      #
+      # @return [ Array < String > ] the list of tracked fields for the given action
+      def tracked_fields_for_action(action)
+        case action.to_sym
+          when :destroy then tracked_fields + reserved_tracked_fields
+          else tracked_fields
+        end
+      end
+
+      # Retrieves the memoized base list of tracked fields, excluding reserved fields.
+      #
+      # @return [ Array < String > ] the base list of tracked database field names
+      def tracked_fields
+        @tracked_fields ||= self.fields.keys.select do |field|
+          h = history_trackable_options
+          (h[:on]==:all || h[:on].include?(field)) && !h[:except].include?(field)
+        end - reserved_tracked_fields
+      end
+
+      # Retrieves the memoized list of reserved tracked fields, which are only included for certain actions.
+      #
+      # @return [ Array < String > ] the list of reserved database field names
+      def reserved_tracked_fields
+        @reserved_tracked_fields ||= ["_id", history_trackable_options[:version_field].to_s, "#{history_trackable_options[:modifier_field]}_id"]
+      end
+
       def history_trackable_options
         @history_trackable_options ||= Mongoid::History.trackable_class_options[self.collection_name.to_s.singularize.to_sym]
       end
+
+      # Indicates whether there is an Embedded::One relation for the given embedded field.
+      #
+      # @param [ String | Symbol ] embed The name of the embedded field
+      #
+      # @return [ Boolean ] true if there is an Embedded::One relation for the given embedded field
+      def embeds_one?(embed)
+        relation_of(embed) == Mongoid::Relations::Embedded::One
+      end
+
+      # Indicates whether there is an Embedded::Many relation for the given embedded field.
+      #
+      # @param [ String | Symbol ] embed The name of the embedded field
+      #
+      # @return [ Boolean ] true if there is an Embedded::Many relation for the given embedded field
+      def embeds_many?(embed)
+        relation_of(embed) == Mongoid::Relations::Embedded::Many
+      end
+
+      # Retrieves the database representation of an embedded field name, in case the :store_as option is used.
+      #
+      # @param [ String | Symbol ] embed The name or alias of the embedded field
+      #
+      # @return [ String ] the database name of the embedded field
+      def embedded_alias(embed)
+        embedded_aliases[embed]
+      end
+
+      protected
+
+      # Retrieves the memoized hash of embedded aliases and their associated database representations.
+      #
+      # @return [ Hash < String, String > ] hash of embedded aliases (keys) to database representations (values)
+      def embedded_aliases
+        @embedded_aliases ||= relations.inject(HashWithIndifferentAccess.new) do |h,(k,v)|
+          h[v[:store_as]||k]=k; h
+        end
+      end
+
+      def relation_of(embed)
+        meta = reflect_on_association(embedded_alias(embed))
+        meta ? meta.relation : nil
+      end
     end
   end
 end