2009-05-27 15:21:20 +00:00
|
|
|
module PaperTrail
|
2010-03-19 17:21:16 +00:00
|
|
|
module Model
|
2009-05-27 15:21:20 +00:00
|
|
|
|
2010-03-19 17:21:16 +00:00
|
|
|
def self.included(base)
|
|
|
|
base.send :extend, ClassMethods
|
2010-06-22 11:48:36 +00:00
|
|
|
|
|
|
|
# The version this instance was reified from.
|
|
|
|
attr_accessor :version
|
2010-03-19 17:21:16 +00:00
|
|
|
end
|
2009-05-27 15:21:20 +00:00
|
|
|
|
|
|
|
|
2010-03-19 17:21:16 +00:00
|
|
|
module ClassMethods
|
2010-03-19 18:53:49 +00:00
|
|
|
# Declare this in your model to track every create, update, and destroy. Each version of
|
|
|
|
# the model is available in the `versions` association.
|
|
|
|
#
|
2010-03-19 17:21:16 +00:00
|
|
|
# Options:
|
2010-03-19 18:53:49 +00:00
|
|
|
# :ignore an array of attributes for which a new `Version` will not be created if only they change.
|
|
|
|
# :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
|
|
|
|
# the controller.
|
2010-03-19 17:21:16 +00:00
|
|
|
def has_paper_trail(options = {})
|
2010-04-06 16:27:15 +00:00
|
|
|
# Lazily include the instance methods so we don't clutter up
|
|
|
|
# any more ActiveRecord models than we have to.
|
2010-03-19 17:21:16 +00:00
|
|
|
send :include, InstanceMethods
|
2009-10-28 13:12:36 +00:00
|
|
|
|
2010-03-19 17:21:16 +00:00
|
|
|
cattr_accessor :ignore
|
|
|
|
self.ignore = (options[:ignore] || []).map &:to_s
|
2010-01-06 12:57:54 +00:00
|
|
|
|
2010-03-19 17:21:16 +00:00
|
|
|
cattr_accessor :meta
|
|
|
|
self.meta = options[:meta] || {}
|
2010-02-18 16:35:41 +00:00
|
|
|
|
2010-03-19 17:21:16 +00:00
|
|
|
# Indicates whether or not PaperTrail is active for this class.
|
|
|
|
# This is independent of whether PaperTrail is globally enabled or disabled.
|
|
|
|
cattr_accessor :paper_trail_active
|
|
|
|
self.paper_trail_active = true
|
2009-05-27 15:21:20 +00:00
|
|
|
|
2010-03-19 17:21:16 +00:00
|
|
|
has_many :versions, :as => :item, :order => 'created_at ASC, id ASC'
|
2009-05-27 15:21:20 +00:00
|
|
|
|
2010-03-19 17:21:16 +00:00
|
|
|
after_create :record_create
|
|
|
|
before_update :record_update
|
|
|
|
after_destroy :record_destroy
|
|
|
|
end
|
2009-05-27 15:21:20 +00:00
|
|
|
|
2010-03-19 17:21:16 +00:00
|
|
|
# Switches PaperTrail off for this class.
|
|
|
|
def paper_trail_off
|
|
|
|
self.paper_trail_active = false
|
|
|
|
end
|
2009-05-27 15:21:20 +00:00
|
|
|
|
2010-03-19 17:21:16 +00:00
|
|
|
# Switches PaperTrail on for this class.
|
|
|
|
def paper_trail_on
|
|
|
|
self.paper_trail_active = true
|
|
|
|
end
|
2009-05-27 15:21:20 +00:00
|
|
|
end
|
|
|
|
|
2010-04-06 16:27:15 +00:00
|
|
|
# Wrap the following methods in a module so we can include them only in the
|
|
|
|
# ActiveRecord models that declare `has_paper_trail`.
|
2010-03-19 17:21:16 +00:00
|
|
|
module InstanceMethods
|
2010-10-21 11:30:50 +00:00
|
|
|
# Returns true if this instance is the current, live one;
|
|
|
|
# returns false if this instance came from a previous version.
|
|
|
|
def live?
|
|
|
|
version.nil?
|
|
|
|
end
|
|
|
|
|
2010-06-28 13:03:35 +00:00
|
|
|
# Returns who put the object into its current state.
|
|
|
|
def originator
|
|
|
|
versions.last.try :whodunnit
|
|
|
|
end
|
|
|
|
|
2010-03-19 17:21:16 +00:00
|
|
|
# Returns the object (not a Version) as it was at the given timestamp.
|
|
|
|
def version_at(timestamp)
|
2010-10-20 12:48:52 +00:00
|
|
|
# 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.first :conditions => ['created_at > ?', timestamp], :order => 'created_at ASC, id ASC'
|
|
|
|
version ? version.reify : self
|
2010-03-19 17:21:16 +00:00
|
|
|
end
|
2009-05-27 15:21:20 +00:00
|
|
|
|
2010-06-22 13:41:26 +00:00
|
|
|
# Returns the object (not a Version) as it was most recently.
|
|
|
|
def previous_version
|
|
|
|
last_version = version ? version.previous : versions.last
|
2010-06-28 10:27:08 +00:00
|
|
|
last_version.try :reify
|
2010-06-22 13:41:26 +00:00
|
|
|
end
|
|
|
|
|
|
|
|
# Returns the object (not a Version) as it became next.
|
|
|
|
def next_version
|
|
|
|
# NOTE: if self (the item) was not reified from a version, i.e. it is the
|
|
|
|
# "live" item, we return nil. Perhaps we should return self instead?
|
|
|
|
subsequent_version = version ? version.next : nil
|
|
|
|
subsequent_version.reify if subsequent_version
|
|
|
|
end
|
|
|
|
|
2010-03-19 17:21:16 +00:00
|
|
|
private
|
2009-05-27 15:21:20 +00:00
|
|
|
|
2010-10-28 10:14:19 +00:00
|
|
|
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
|
|
|
|
|
2010-03-19 17:21:16 +00:00
|
|
|
def merge_metadata(data)
|
2010-03-19 18:53:49 +00:00
|
|
|
# First we merge the model-level metadata in `meta`.
|
2010-03-19 17:21:16 +00:00
|
|
|
meta.each do |k,v|
|
|
|
|
data[k] = v.respond_to?(:call) ? v.call(self) : v
|
|
|
|
end
|
2010-03-19 18:53:49 +00:00
|
|
|
# Second we merge any extra data from the controller (if available).
|
|
|
|
data.merge(PaperTrail.controller_info || {})
|
2010-01-06 12:57:54 +00:00
|
|
|
end
|
|
|
|
|
2010-06-22 13:41:26 +00:00
|
|
|
def item_before_change
|
2010-03-19 17:21:16 +00:00
|
|
|
previous = self.clone
|
|
|
|
previous.id = id
|
|
|
|
changes.each do |attr, ary|
|
2010-10-28 09:15:15 +00:00
|
|
|
previous.send :write_attribute, attr.to_sym, ary.first
|
2010-03-19 17:21:16 +00:00
|
|
|
end
|
|
|
|
previous
|
2009-05-27 15:21:20 +00:00
|
|
|
end
|
|
|
|
|
2010-03-19 17:21:16 +00:00
|
|
|
def object_to_string(object)
|
|
|
|
object.attributes.to_yaml
|
|
|
|
end
|
2009-10-28 13:12:36 +00:00
|
|
|
|
2010-03-19 17:21:16 +00:00
|
|
|
def changed_and_we_care?
|
|
|
|
changed? and !(changed - self.class.ignore).empty?
|
|
|
|
end
|
2010-03-19 15:21:07 +00:00
|
|
|
|
2010-03-19 17:21:16 +00:00
|
|
|
# Returns `true` if PaperTrail is globally enabled and active for this class,
|
|
|
|
# `false` otherwise.
|
|
|
|
def switched_on?
|
|
|
|
PaperTrail.enabled? && self.class.paper_trail_active
|
|
|
|
end
|
2010-03-19 15:21:07 +00:00
|
|
|
end
|
2009-05-27 15:21:20 +00:00
|
|
|
|
2010-03-19 17:21:16 +00:00
|
|
|
end
|
2009-05-27 15:21:20 +00:00
|
|
|
end
|
|
|
|
|
2010-03-19 17:21:16 +00:00
|
|
|
ActiveRecord::Base.send :include, PaperTrail::Model
|