diff --git a/CHANGELOG.md b/CHANGELOG.md index c0b53b6b..bbdfd279 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,8 @@ recommendations of [keepachangelog.com](http://keepachangelog.com/). ### Added +- [#1166](https://github.com/paper-trail-gem/paper_trail/pull/1166) - + New global option `has_paper_trail_defaults`, defaults for `has_paper_trail` - [#1158](https://github.com/paper-trail-gem/paper_trail/pull/1158) — Add the ability to pass options, such as `scope` or `extend:` to the `has_many :versions` association macro. diff --git a/README.md b/README.md index b7eb4570..2fbb3ba2 100644 --- a/README.md +++ b/README.md @@ -268,6 +268,33 @@ A common place to put these settings is in a Rails initializer file such as `config/initializers/paper_trail.rb` or in an environment-specific configuration file such as `config/environments/test.rb`. +#### 1.e.1 Global + +Global configuration options affect all threads. + +- association_reify_error_behaviour +- enabled +- has_paper_trail_defaults +- object_changes_adapter +- serializer +- version_limit + +Syntax example: (options described in detail later) + +```ruby +# config/initializers/paper_trail.rb +PaperTrail.config.enabled = true +PaperTrail.config.has_paper_trail_defaults = { + on: %i[create update destroy] +} +PaperTrail.config.version_limit = 3 +```` + +These options are intended to be set only once, during app initialization (eg. +in `config/initializers`). It is unsafe to change them while the app is running. +In contrast, `PaperTrail.request` has various options that only apply to a +single HTTP request and thus are safe to use while the app is running. + ## 2. Limiting What is Versioned, and When ### 2.a. Choosing Lifecycle Events To Monitor @@ -492,7 +519,7 @@ PaperTrail.request(enabled: false) do end ``` -or, +or, ```ruby PaperTrail.request.enabled = false @@ -543,7 +570,7 @@ It would be better to install your own callback and use The `widget.paper_trail.without_versioning` method was removed in v10, without an exact replacement. To disable versioning, use the [Per Class](#per-class) or -[Per HTTP Request](#per-http-request) methods. +[Per HTTP Request](#per-http-request) methods. ### 2.e. Limiting the Number of Versions Created @@ -617,8 +644,8 @@ previous and next versions. ```ruby widget = Widget.find 42 version = widget.versions[-2] # assuming widget has several versions -previous = version.previous -next = version.next +previous_version = version.previous +next_version = version.next ``` You can find out which of an item's versions yours is: @@ -1000,7 +1027,6 @@ end Overriding (instead of configuring) the `versions` method is not supported. Overriding associations is not recommended in general. - ### 5.c. Generators PaperTrail has one generator, `paper_trail:install`. It writes, but does not diff --git a/lib/paper_trail/config.rb b/lib/paper_trail/config.rb index 957b4e31..f2e9388b 100644 --- a/lib/paper_trail/config.rb +++ b/lib/paper_trail/config.rb @@ -21,7 +21,8 @@ module PaperTrail :association_reify_error_behaviour, :object_changes_adapter, :serializer, - :version_limit + :version_limit, + :has_paper_trail_defaults ) def initialize @@ -31,6 +32,7 @@ module PaperTrail # Variables which affect all threads, whose access is *not* synchronized. @serializer = PaperTrail::Serializers::YAML + @has_paper_trail_defaults = {} end # Indicates whether PaperTrail is on or off. Default: true. diff --git a/lib/paper_trail/has_paper_trail.rb b/lib/paper_trail/has_paper_trail.rb index 3aadabd7..323817a7 100644 --- a/lib/paper_trail/has_paper_trail.rb +++ b/lib/paper_trail/has_paper_trail.rb @@ -23,18 +23,18 @@ module PaperTrail # Options: # # - :on - The events to track (optional; defaults to all of them). Set - # to an array of `:create`, `:update`, `:destroy` as desired. + # to an array of `:create`, `:update`, `:destroy` and `:touch` as desired. # - :class_name (deprecated) - The name of a custom Version class that # includes `PaperTrail::VersionConcern`. # - :ignore - An array of attributes for which a new `Version` will not be - # created if only they change. It can also aceept a Hash as an + # 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 aceept a Hash as an + # 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. @@ -57,9 +57,15 @@ module PaperTrail # Plugins like the experimental `paper_trail-association_tracking` gem # may accept additional options. # + # You can define a default set of options via the configurable + # `PaperTrail.config.has_paper_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. + # # @api public def has_paper_trail(options = {}) - paper_trail.setup(options) + defaults = PaperTrail.config.has_paper_trail_defaults + paper_trail.setup(defaults.merge(options)) end # @api public