Docs: Organize readme re: limiting what/when
Group together readme sections about limiting what is versioned, and when. [ci skip]
This commit is contained in:
parent
b389c94327
commit
b7dc57c448
243
README.md
243
README.md
|
@ -11,9 +11,12 @@ revert it to any version, and even undelete it after it's been destroyed.
|
||||||
- [Installation](#installation)
|
- [Installation](#installation)
|
||||||
- [API Summary](#api-summary)
|
- [API Summary](#api-summary)
|
||||||
- [Basic Usage](#basic-usage)
|
- [Basic Usage](#basic-usage)
|
||||||
- [Choosing Lifecycle Events To Monitor](#choosing-lifecycle-events-to-monitor)
|
- Limiting what is versioned, and when
|
||||||
- [Choosing When To Save New Versions](#choosing-when-to-save-new-versions)
|
- [Choosing Lifecycle Events To Monitor](#choosing-lifecycle-events-to-monitor)
|
||||||
- [Choosing Attributes To Monitor](#choosing-attributes-to-monitor)
|
- [Choosing When To Save New Versions](#choosing-when-to-save-new-versions)
|
||||||
|
- [Choosing Attributes To Monitor](#choosing-attributes-to-monitor)
|
||||||
|
- [Turning PaperTrail Off/On](#turning-papertrail-offon)
|
||||||
|
- [Limiting the Number of Versions Created](#limiting-the-number-of-versions-created)
|
||||||
- [Reverting And Undeleting A Model](#reverting-and-undeleting-a-model)
|
- [Reverting And Undeleting A Model](#reverting-and-undeleting-a-model)
|
||||||
- [Navigating Versions](#navigating-versions)
|
- [Navigating Versions](#navigating-versions)
|
||||||
- [Finding Out Who Was Responsible For A Change](#finding-out-who-was-responsible-for-a-change)
|
- [Finding Out Who Was Responsible For A Change](#finding-out-who-was-responsible-for-a-change)
|
||||||
|
@ -21,10 +24,8 @@ revert it to any version, and even undelete it after it's been destroyed.
|
||||||
- [Associations](#associations)
|
- [Associations](#associations)
|
||||||
- [Storing metadata](#storing-metadata)
|
- [Storing metadata](#storing-metadata)
|
||||||
- [Diffing Versions](#diffing-versions)
|
- [Diffing Versions](#diffing-versions)
|
||||||
- [Turning PaperTrail Off/On](#turning-papertrail-offon)
|
|
||||||
- [Using a custom serializer](#using-a-custom-serializer)
|
- [Using a custom serializer](#using-a-custom-serializer)
|
||||||
- [SerializedAttributes support](#serializedattributes-support)
|
- [SerializedAttributes support](#serializedattributes-support)
|
||||||
- [Limiting the Number of Versions Created](#limiting-the-number-of-versions-created)
|
|
||||||
- [Deleting Old Versions](#deleting-old-versions)
|
- [Deleting Old Versions](#deleting-old-versions)
|
||||||
- [Testing](#testing)
|
- [Testing](#testing)
|
||||||
|
|
||||||
|
@ -437,6 +438,122 @@ class Article < ActiveRecord::Base
|
||||||
end
|
end
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## Turning PaperTrail Off/On
|
||||||
|
|
||||||
|
Sometimes you don't want to store changes. Perhaps you are only interested in
|
||||||
|
changes made by your users and don't need to store changes you make yourself in,
|
||||||
|
say, a migration -- or when testing your application.
|
||||||
|
|
||||||
|
You can turn PaperTrail on or off in three ways: globally, per request, or per
|
||||||
|
class.
|
||||||
|
|
||||||
|
### Globally
|
||||||
|
|
||||||
|
On a global level you can turn PaperTrail off like this:
|
||||||
|
|
||||||
|
```ruby
|
||||||
|
PaperTrail.enabled = false
|
||||||
|
```
|
||||||
|
|
||||||
|
For example, you might want to disable PaperTrail in your Rails application's
|
||||||
|
test environment to speed up your tests. This will do it (note: this gets done
|
||||||
|
automatically for `RSpec` and `Cucumber`, please see the [Testing
|
||||||
|
section](#testing)):
|
||||||
|
|
||||||
|
```ruby
|
||||||
|
# in config/environments/test.rb
|
||||||
|
config.after_initialize do
|
||||||
|
PaperTrail.enabled = false
|
||||||
|
end
|
||||||
|
```
|
||||||
|
|
||||||
|
If you disable PaperTrail in your test environment but want to enable it for
|
||||||
|
specific tests, you can add a helper like this to your test helper:
|
||||||
|
|
||||||
|
```ruby
|
||||||
|
# in test/test_helper.rb
|
||||||
|
def with_versioning
|
||||||
|
was_enabled = PaperTrail.enabled?
|
||||||
|
was_enabled_for_controller = PaperTrail.enabled_for_controller?
|
||||||
|
PaperTrail.enabled = true
|
||||||
|
PaperTrail.enabled_for_controller = true
|
||||||
|
begin
|
||||||
|
yield
|
||||||
|
ensure
|
||||||
|
PaperTrail.enabled = was_enabled
|
||||||
|
PaperTrail.enabled_for_controller = was_enabled_for_controller
|
||||||
|
end
|
||||||
|
end
|
||||||
|
```
|
||||||
|
|
||||||
|
And then use it in your tests like this:
|
||||||
|
|
||||||
|
```ruby
|
||||||
|
test "something that needs versioning" do
|
||||||
|
with_versioning do
|
||||||
|
# your test
|
||||||
|
end
|
||||||
|
end
|
||||||
|
```
|
||||||
|
|
||||||
|
### Per request
|
||||||
|
|
||||||
|
You can turn PaperTrail on or off per request by adding a
|
||||||
|
`paper_trail_enabled_for_controller` method to your controller which returns
|
||||||
|
`true` or `false`:
|
||||||
|
|
||||||
|
```ruby
|
||||||
|
class ApplicationController < ActionController::Base
|
||||||
|
def paper_trail_enabled_for_controller
|
||||||
|
request.user_agent != 'Disable User-Agent'
|
||||||
|
end
|
||||||
|
end
|
||||||
|
```
|
||||||
|
|
||||||
|
### Per class
|
||||||
|
|
||||||
|
If you are about to change some widgets and you don't want a paper trail of your
|
||||||
|
changes, you can turn PaperTrail off like this:
|
||||||
|
|
||||||
|
```ruby
|
||||||
|
Widget.paper_trail_off!
|
||||||
|
```
|
||||||
|
|
||||||
|
And on again like this:
|
||||||
|
|
||||||
|
```ruby
|
||||||
|
Widget.paper_trail_on!
|
||||||
|
```
|
||||||
|
|
||||||
|
### Per method call
|
||||||
|
|
||||||
|
You can call a method without creating a new version using `without_versioning`.
|
||||||
|
It takes either a method name as a symbol:
|
||||||
|
|
||||||
|
```ruby
|
||||||
|
@widget.without_versioning :destroy
|
||||||
|
```
|
||||||
|
|
||||||
|
Or a block:
|
||||||
|
|
||||||
|
```ruby
|
||||||
|
@widget.without_versioning do
|
||||||
|
@widget.update_attributes :name => 'Ford'
|
||||||
|
end
|
||||||
|
```
|
||||||
|
|
||||||
|
## Limiting the Number of Versions Created
|
||||||
|
|
||||||
|
Configure `version_limit` to cap the number of versions saved per record. This
|
||||||
|
does not apply to `create` events.
|
||||||
|
|
||||||
|
```ruby
|
||||||
|
# Limit: 4 versions per record (3 most recent, plus a `create` event)
|
||||||
|
PaperTrail.config.version_limit = 3
|
||||||
|
# Remove the limit
|
||||||
|
PaperTrail.config.version_limit = nil
|
||||||
|
```
|
||||||
|
|
||||||
## Reverting And Undeleting A Model
|
## Reverting And Undeleting A Model
|
||||||
|
|
||||||
PaperTrail makes reverting to a previous version easy:
|
PaperTrail makes reverting to a previous version easy:
|
||||||
|
@ -956,110 +1073,6 @@ If you wish to selectively record changes for some models but not others you
|
||||||
can opt out of recording changes by passing `:save_changes => false` to your
|
can opt out of recording changes by passing `:save_changes => false` to your
|
||||||
`has_paper_trail` method declaration.
|
`has_paper_trail` method declaration.
|
||||||
|
|
||||||
## Turning PaperTrail Off/On
|
|
||||||
|
|
||||||
Sometimes you don't want to store changes. Perhaps you are only interested in
|
|
||||||
changes made by your users and don't need to store changes you make yourself in,
|
|
||||||
say, a migration -- or when testing your application.
|
|
||||||
|
|
||||||
You can turn PaperTrail on or off in three ways: globally, per request, or per
|
|
||||||
class.
|
|
||||||
|
|
||||||
### Globally
|
|
||||||
|
|
||||||
On a global level you can turn PaperTrail off like this:
|
|
||||||
|
|
||||||
```ruby
|
|
||||||
PaperTrail.enabled = false
|
|
||||||
```
|
|
||||||
|
|
||||||
For example, you might want to disable PaperTrail in your Rails application's
|
|
||||||
test environment to speed up your tests. This will do it (note: this gets done
|
|
||||||
automatically for `RSpec` and `Cucumber`, please see the [Testing
|
|
||||||
section](#testing)):
|
|
||||||
|
|
||||||
```ruby
|
|
||||||
# in config/environments/test.rb
|
|
||||||
config.after_initialize do
|
|
||||||
PaperTrail.enabled = false
|
|
||||||
end
|
|
||||||
```
|
|
||||||
|
|
||||||
If you disable PaperTrail in your test environment but want to enable it for
|
|
||||||
specific tests, you can add a helper like this to your test helper:
|
|
||||||
|
|
||||||
```ruby
|
|
||||||
# in test/test_helper.rb
|
|
||||||
def with_versioning
|
|
||||||
was_enabled = PaperTrail.enabled?
|
|
||||||
was_enabled_for_controller = PaperTrail.enabled_for_controller?
|
|
||||||
PaperTrail.enabled = true
|
|
||||||
PaperTrail.enabled_for_controller = true
|
|
||||||
begin
|
|
||||||
yield
|
|
||||||
ensure
|
|
||||||
PaperTrail.enabled = was_enabled
|
|
||||||
PaperTrail.enabled_for_controller = was_enabled_for_controller
|
|
||||||
end
|
|
||||||
end
|
|
||||||
```
|
|
||||||
|
|
||||||
And then use it in your tests like this:
|
|
||||||
|
|
||||||
```ruby
|
|
||||||
test "something that needs versioning" do
|
|
||||||
with_versioning do
|
|
||||||
# your test
|
|
||||||
end
|
|
||||||
end
|
|
||||||
```
|
|
||||||
|
|
||||||
### Per request
|
|
||||||
|
|
||||||
You can turn PaperTrail on or off per request by adding a
|
|
||||||
`paper_trail_enabled_for_controller` method to your controller which returns
|
|
||||||
`true` or `false`:
|
|
||||||
|
|
||||||
```ruby
|
|
||||||
class ApplicationController < ActionController::Base
|
|
||||||
def paper_trail_enabled_for_controller
|
|
||||||
request.user_agent != 'Disable User-Agent'
|
|
||||||
end
|
|
||||||
end
|
|
||||||
```
|
|
||||||
|
|
||||||
### Per class
|
|
||||||
|
|
||||||
If you are about to change some widgets and you don't want a paper trail of your
|
|
||||||
changes, you can turn PaperTrail off like this:
|
|
||||||
|
|
||||||
```ruby
|
|
||||||
Widget.paper_trail_off!
|
|
||||||
```
|
|
||||||
|
|
||||||
And on again like this:
|
|
||||||
|
|
||||||
```ruby
|
|
||||||
Widget.paper_trail_on!
|
|
||||||
```
|
|
||||||
|
|
||||||
### Per method call
|
|
||||||
|
|
||||||
You can call a method without creating a new version using `without_versioning`.
|
|
||||||
It takes either a method name as a symbol:
|
|
||||||
|
|
||||||
```ruby
|
|
||||||
@widget.without_versioning :destroy
|
|
||||||
```
|
|
||||||
|
|
||||||
Or a block:
|
|
||||||
|
|
||||||
```ruby
|
|
||||||
@widget.without_versioning do
|
|
||||||
@widget.update_attributes :name => 'Ford'
|
|
||||||
end
|
|
||||||
```
|
|
||||||
|
|
||||||
## Using a custom serializer
|
## Using a custom serializer
|
||||||
|
|
||||||
By default, PaperTrail stores your changes as a `YAML` dump. You can override
|
By default, PaperTrail stores your changes as a `YAML` dump. You can override
|
||||||
|
@ -1112,18 +1125,6 @@ PaperTrail.config.serialized_attributes = false
|
||||||
PaperTrail.serialized_attributes?
|
PaperTrail.serialized_attributes?
|
||||||
```
|
```
|
||||||
|
|
||||||
## Limiting the Number of Versions Created
|
|
||||||
|
|
||||||
Configure `version_limit` to cap the number of versions saved per record. This
|
|
||||||
does not apply to `create` events.
|
|
||||||
|
|
||||||
```ruby
|
|
||||||
# Limit: 4 versions per record (3 most recent, plus a `create` event)
|
|
||||||
PaperTrail.config.version_limit = 3
|
|
||||||
# Remove the limit
|
|
||||||
PaperTrail.config.version_limit = nil
|
|
||||||
```
|
|
||||||
|
|
||||||
## Deleting Old Versions
|
## Deleting Old Versions
|
||||||
|
|
||||||
Over time your `versions` table will grow to an unwieldy size. Because each
|
Over time your `versions` table will grow to an unwieldy size. Because each
|
||||||
|
|
Loading…
Reference in New Issue