Module: SnailTrail::Model::ClassMethods

Defined in:
lib/snail_trail/has_snail_trail.rb

Overview

:nodoc:

Instance Method Summary collapse

Instance Method Details

#has_snail_trail(options = {}) ⇒ Object

Declare this in your model to track every create, update, and destroy. Each version of the model is available in the versions association.

Options:

  • :on - The events to track (optional; defaults to all of them). Set to an array of :create, :update, :destroy and :touch as desired.
  • :class_name (deprecated) - The name of a custom Version class that includes SnailTrail::VersionConcern.
  • :ignore - An array of attributes for which a new Version will not be created if only they change. It can also accept a Hash as an argument where the key is the attribute to ignore (a String or Symbol), which will only be ignored if the value is a Proc which returns truthily.
  • :if, :unless - Procs that allow to specify conditions when to save versions for an object.
  • :only - Inverse of ignore. A new Version will be created only for these attributes if supplied it can also accept a Hash as an argument where the key is the attribute to track (a String or Symbol), which will only be counted if the value is a Proc which returns truthily.
  • :skip - Fields to ignore completely. As with ignore, updates to these fields will not create a new Version. In addition, these fields will not be included in the serialized versions of the object whenever a new Version is created.
  • :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 snail trail). See SnailTrail::Controller.info_for_snail_trail for how to store data from the controller.
  • :versions - Either,
    • A String (deprecated) - The name to use for the versions association. Default is :versions.
    • A Hash - options passed to has_many, plus name: and scope:.
  • :version - The name to use for the method which returns the version the instance was reified from. Default is :version.
  • :synchronize_version_creation_timestamp - By default, snail trail sets the created_at field for a new Version equal to the updated_at column of the model being updated. If you instead want created_at to populate with the current timestamp, set this option to false.

Plugins like the experimental snail_trail-association_tracking gem may accept additional options.

You can define a default set of options via the configurable SnailTrail.config.has_snail_trail_defaults hash in your applications initializer. The hash can contain any of the following options and will provide an overridable default for all models.

Raises:



70
71
72
73
74
75
 
# File 'lib/snail_trail/has_snail_trail.rb', line 70

def has_snail_trail(options = {})
  raise Error, "has_snail_trail must be called only once" if self < InstanceMethods

  defaults = SnailTrail.config.has_snail_trail_defaults
  snail_trail.setup(defaults.merge(options))
end

#snail_trail ⇒ Object 



78
79
80
 
# File 'lib/snail_trail/has_snail_trail.rb', line 78

def snail_trail
  ::SnailTrail::ModelConfig.new(self)
end