versioned associates an
ActiveRecord model with many versions. When the object is updated, a new
version containing the changes is created. There are several options
available to the versioned
method, most of which are passed to the has_many association
itself:
- :class_name: The class name of the version model to use for the
association. By default, this is set to "VestalVersions::Version", representing the
built-in version class. By specifying this option, you can override the
version class, to include custom version behavior. It‘s recommended
that a custom version inherit from VestalVersions::Version.
- :dependent: Also common to has_many associations, this
describes the behavior of version records when the parent object is
destroyed. This defaults to :delete_all, which will permanently remove all
associated versions without triggering any destroy callbacks. Other
options are :destroy which removes the associated versions with
callbacks, or :nullify which leaves the version records in the database,
but dissociates them from the parent object by setting the foreign key
columns to nil values.
- :except: An update will trigger version creation as long as at
least one column outside those specified here was updated. Also, upon
version creation, the columns specified here will be excluded from the
change history. This is useful when dealing with unimportant, constantly
changing, or sensitive information. This option accepts a symbol, string or
an array of either, representing column names to exclude. It is completely
optional and defaults to nil, allowing all columns to be versioned. This option is also ignored
if the only option is used.
- :extend: This option allows you to extend the has_many
association proxy with a module or an array of modules. Any methods defined
in those modules become available on the versions association. The
VestalVersions::Versions module is essential to
the functionality of vestal_versions and so is prepended to any
additional modules that you might specify here.
- :if: Accepts a symbol, a proc or an array of either to be
evaluated when the parent object is updated to determine whether a new
version should be created. to_proc is called on any symbols given
and the resulting procs are called, passing in the object itself. If an
array is given, all must be evaluate to true in order for a
version to be created.
- :only: An update will trigger version creation as long as at least
one updated column falls within those specified here. Also, upon version
creation, only the columns specified here will be included in the change
history. This option accepts a symbol, string or an array of either,
representing column names to include. It is completely optional and
defaults to nil, allowing all columns to be versioned. This option takes
precedence over the except option if both are specified.
- :unless: Accepts a symbol, a proc or an array of either to be
evaluated when the parent object is updated to determine whether version
creation should be skipped. to_proc is called on any symbols given
and the resulting procs are called, passing in the object itself. If an
array is given and any element evaluates as true, the version
creation will be skipped.