2009-05-27 11:21:20 -04:00
|
|
|
module PaperTrail
|
2010-03-19 13:21:16 -04:00
|
|
|
module Model
|
2009-05-27 11:21:20 -04:00
|
|
|
|
2010-03-19 13:21:16 -04:00
|
|
|
def self.included(base)
|
|
|
|
base.send :extend, ClassMethods
|
|
|
|
end
|
2009-05-27 11:21:20 -04:00
|
|
|
|
|
|
|
|
2010-03-19 13:21:16 -04:00
|
|
|
module ClassMethods
|
2010-03-19 14:53:49 -04: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 13:21:16 -04:00
|
|
|
# Options:
|
2010-03-19 14:53:49 -04: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 13:21:16 -04:00
|
|
|
def has_paper_trail(options = {})
|
2010-04-06 12:27:15 -04:00
|
|
|
# Lazily include the instance methods so we don't clutter up
|
|
|
|
# any more ActiveRecord models than we have to.
|
2010-03-19 13:21:16 -04:00
|
|
|
send :include, InstanceMethods
|
2009-10-28 09:12:36 -04:00
|
|
|
|
2010-03-19 13:21:16 -04:00
|
|
|
cattr_accessor :ignore
|
|
|
|
self.ignore = (options[:ignore] || []).map &:to_s
|
2010-01-06 07:57:54 -05:00
|
|
|
|
2010-03-19 13:21:16 -04:00
|
|
|
cattr_accessor :meta
|
|
|
|
self.meta = options[:meta] || {}
|
2010-02-18 11:35:41 -05:00
|
|
|
|
2010-03-19 13:21:16 -04: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 11:21:20 -04:00
|
|
|
|
2010-03-19 13:21:16 -04:00
|
|
|
has_many :versions, :as => :item, :order => 'created_at ASC, id ASC'
|
2009-05-27 11:21:20 -04:00
|
|
|
|
2010-03-19 13:21:16 -04:00
|
|
|
after_create :record_create
|
|
|
|
before_update :record_update
|
|
|
|
after_destroy :record_destroy
|
|
|
|
end
|
2009-05-27 11:21:20 -04:00
|
|
|
|
2010-03-19 13:21:16 -04:00
|
|
|
# Switches PaperTrail off for this class.
|
|
|
|
def paper_trail_off
|
|
|
|
self.paper_trail_active = false
|
|
|
|
end
|
2009-05-27 11:21:20 -04:00
|
|
|
|
2010-03-19 13:21:16 -04:00
|
|
|
# Switches PaperTrail on for this class.
|
|
|
|
def paper_trail_on
|
|
|
|
self.paper_trail_active = true
|
|
|
|
end
|
2009-05-27 11:21:20 -04:00
|
|
|
end
|
|
|
|
|
2010-04-06 12:27:15 -04: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 13:21:16 -04:00
|
|
|
module InstanceMethods
|
|
|
|
def record_create
|
|
|
|
if switched_on?
|
|
|
|
versions.create merge_metadata(:event => 'create', :whodunnit => PaperTrail.whodunnit)
|
|
|
|
end
|
2010-01-06 07:57:54 -05:00
|
|
|
end
|
2009-05-27 11:21:20 -04:00
|
|
|
|
2010-03-19 13:21:16 -04:00
|
|
|
def record_update
|
|
|
|
if switched_on? && changed_and_we_care?
|
|
|
|
versions.build merge_metadata(:event => 'update',
|
|
|
|
:object => object_to_string(previous_version),
|
|
|
|
:whodunnit => PaperTrail.whodunnit)
|
|
|
|
end
|
2009-05-27 11:21:20 -04:00
|
|
|
end
|
|
|
|
|
2010-03-19 13:21:16 -04:00
|
|
|
def record_destroy
|
|
|
|
if switched_on?
|
|
|
|
versions.create merge_metadata(:event => 'destroy',
|
|
|
|
:object => object_to_string(previous_version),
|
|
|
|
:whodunnit => PaperTrail.whodunnit)
|
|
|
|
end
|
2010-01-06 07:57:54 -05:00
|
|
|
end
|
2010-02-18 11:35:41 -05:00
|
|
|
|
2010-03-19 13:21:16 -04:00
|
|
|
# Returns the object (not a Version) as it was at the given timestamp.
|
|
|
|
def version_at(timestamp)
|
|
|
|
# Short-circuit if the current state is applicable.
|
|
|
|
return self if self.updated_at <= timestamp
|
|
|
|
# Look for the first version created after, rather than before, the
|
|
|
|
# timestamp because a version stores how the object looked before the
|
|
|
|
# change.
|
|
|
|
version = versions.first :conditions => ['created_at > ?', timestamp],
|
|
|
|
:order => 'created_at ASC'
|
|
|
|
version.reify if version
|
|
|
|
end
|
2009-05-27 11:21:20 -04:00
|
|
|
|
2010-03-19 13:21:16 -04:00
|
|
|
private
|
2009-05-27 11:21:20 -04:00
|
|
|
|
2010-03-19 13:21:16 -04:00
|
|
|
def merge_metadata(data)
|
2010-03-19 14:53:49 -04:00
|
|
|
# First we merge the model-level metadata in `meta`.
|
2010-03-19 13:21:16 -04:00
|
|
|
meta.each do |k,v|
|
|
|
|
data[k] = v.respond_to?(:call) ? v.call(self) : v
|
|
|
|
end
|
2010-03-19 14:53:49 -04:00
|
|
|
# Second we merge any extra data from the controller (if available).
|
|
|
|
data.merge(PaperTrail.controller_info || {})
|
2010-01-06 07:57:54 -05:00
|
|
|
end
|
|
|
|
|
2010-03-19 13:21:16 -04:00
|
|
|
def previous_version
|
|
|
|
previous = self.clone
|
|
|
|
previous.id = id
|
|
|
|
changes.each do |attr, ary|
|
|
|
|
previous.send "#{attr}=", ary.first
|
|
|
|
end
|
|
|
|
previous
|
2009-05-27 11:21:20 -04:00
|
|
|
end
|
|
|
|
|
2010-03-19 13:21:16 -04:00
|
|
|
def object_to_string(object)
|
|
|
|
object.attributes.to_yaml
|
|
|
|
end
|
2009-10-28 09:12:36 -04:00
|
|
|
|
2010-03-19 13:21:16 -04:00
|
|
|
def changed_and_we_care?
|
|
|
|
changed? and !(changed - self.class.ignore).empty?
|
|
|
|
end
|
2010-03-19 11:21:07 -04:00
|
|
|
|
2010-03-19 13:21:16 -04: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 11:21:07 -04:00
|
|
|
end
|
2009-05-27 11:21:20 -04:00
|
|
|
|
2010-03-19 13:21:16 -04:00
|
|
|
end
|
2009-05-27 11:21:20 -04:00
|
|
|
end
|
|
|
|
|
2010-03-19 13:21:16 -04:00
|
|
|
ActiveRecord::Base.send :include, PaperTrail::Model
|