Docs: Add ordinal numbers to headers in readme
Numbering the headers improves document navigation and reference-ability. Unfortunately, it does break the anchor part of links in the wild. [ci skip]
This commit is contained in:
parent
29c0dc9335
commit
717193e570
195
README.md
195
README.md
|
@ -19,34 +19,38 @@ has been destroyed.
|
||||||
|
|
||||||
## Table of Contents
|
## Table of Contents
|
||||||
|
|
||||||
- [Compatibility](#compatibility)
|
- [1. Introduction](#1-introduction)
|
||||||
- [Installation](#installation)
|
- [1.a. Compatibility](#1a-compatibility)
|
||||||
- [Basic Usage](#basic-usage)
|
- [1.b. Installation](#1b-installation)
|
||||||
- [API Summary](#api-summary)
|
- [1.c. Basic Usage](#1c-basic-usage)
|
||||||
- Limiting What is Versioned, and When
|
- [1.d. API Summary](#1d-api-summary)
|
||||||
- [Choosing Lifecycle Events To Monitor](#choosing-lifecycle-events-to-monitor)
|
- [2. Limiting What is Versioned, and When](#2-limiting-what-is-versioned-and-when)
|
||||||
- [Choosing When To Save New Versions](#choosing-when-to-save-new-versions)
|
- [2.a. Choosing Lifecycle Events To Monitor](#2a-choosing-lifecycle-events-to-monitor)
|
||||||
- [Choosing Attributes To Monitor](#choosing-attributes-to-monitor)
|
- [2.b. Choosing When To Save New Versions](#2b-choosing-when-to-save-new-versions)
|
||||||
- [Turning PaperTrail Off](#turning-papertrail-off)
|
- [2.c. Choosing Attributes To Monitor](#2c-choosing-attributes-to-monitor)
|
||||||
- [Limiting the Number of Versions Created](#limiting-the-number-of-versions-created)
|
- [2.d. Turning PaperTrail Off](#2d-turning-papertrail-off)
|
||||||
- Working With Versions
|
- [2.e. Limiting the Number of Versions Created](#2e-limiting-the-number-of-versions-created)
|
||||||
- [Reverting And Undeleting A Model](#reverting-and-undeleting-a-model)
|
- [3. Working With Versions](#3-working-with-versions)
|
||||||
- [Navigating Versions](#navigating-versions)
|
- [3.a. Reverting And Undeleting A Model](#3a-reverting-and-undeleting-a-model)
|
||||||
- [Diffing Versions](#diffing-versions)
|
- [3.b. Navigating Versions](#3b-navigating-versions)
|
||||||
- [Deleting Old Versions](#deleting-old-versions)
|
- [3.c. Diffing Versions](#3c-diffing-versions)
|
||||||
- Saving More Information About Versions
|
- [3.d. Deleting Old Versions](#3d-deleting-old-versions)
|
||||||
- [Finding Out Who Was Responsible For A Change](#finding-out-who-was-responsible-for-a-change)
|
- [4. Saving More Information About Versions](#4-saving-more-information-about-versions)
|
||||||
- [Associations](#associations)
|
- [4.a. Finding Out Who Was Responsible For A Change](#4a-finding-out-who-was-responsible-for-a-change)
|
||||||
- [Storing metadata](#storing-metadata)
|
- [4.b. Associations](#4b-associations)
|
||||||
- ActiveRecord
|
- [4.c. Storing metadata](#4c-storing-metadata)
|
||||||
- [Single Table Inheritance](#single-table-inheritance-sti)
|
- [5. ActiveRecord](#5-activerecord)
|
||||||
- Extensibility
|
- [5.a. Single Table Inheritance](#5a-single-table-inheritance-sti)
|
||||||
- [Custom Version Classes](#custom-version-classes)
|
- [5.b. Configuring the `versions` Association](#5b-configuring-the-versions-association)
|
||||||
- [Custom Serializer](#custom-serializer)
|
- [6. Extensibility](#6-extensibility)
|
||||||
- [Testing](#testing)
|
- [6.a. Custom Version Classes](#6a-custom-version-classes)
|
||||||
- [Sinatra](#sinatra)
|
- [6.b. Custom Serializer](#6b-custom-serializer)
|
||||||
|
- [7. Testing](#7-testing)
|
||||||
|
- [8. Sinatra](#8-sinatra)
|
||||||
|
|
||||||
## Compatibility
|
## 1. Introduction
|
||||||
|
|
||||||
|
### 1.a. Compatibility
|
||||||
|
|
||||||
| paper_trail | branch | tags | ruby | activerecord |
|
| paper_trail | branch | tags | ruby | activerecord |
|
||||||
| -------------- | ---------- | ------ | -------- | ------------ |
|
| -------------- | ---------- | ------ | -------- | ------------ |
|
||||||
|
@ -56,7 +60,7 @@ has been destroyed.
|
||||||
| 2 | 2.7-stable | v2.x | >= 1.8.7 | >= 3.0, < 4 |
|
| 2 | 2.7-stable | v2.x | >= 1.8.7 | >= 3.0, < 4 |
|
||||||
| 1 | rails2 | v1.x | >= 1.8.7 | >= 2.3, < 3 |
|
| 1 | rails2 | v1.x | >= 1.8.7 | >= 2.3, < 3 |
|
||||||
|
|
||||||
## Installation
|
### 1.b. Installation
|
||||||
|
|
||||||
1. Add PaperTrail to your `Gemfile`.
|
1. Add PaperTrail to your `Gemfile`.
|
||||||
|
|
||||||
|
@ -90,7 +94,7 @@ by adding a controller callback.
|
||||||
end
|
end
|
||||||
```
|
```
|
||||||
|
|
||||||
## Basic Usage
|
### 1.c. Basic Usage
|
||||||
|
|
||||||
Your models now have a `versions` method which returns the "paper trail" of
|
Your models now have a `versions` method which returns the "paper trail" of
|
||||||
changes to your model.
|
changes to your model.
|
||||||
|
@ -146,7 +150,7 @@ Here's a helpful table showing what PaperTrail stores:
|
||||||
PaperTrail stores the values in the Model Before column. Most other
|
PaperTrail stores the values in the Model Before column. Most other
|
||||||
auditing/versioning plugins store the After column.
|
auditing/versioning plugins store the After column.
|
||||||
|
|
||||||
## API Summary
|
### 1.d. API Summary
|
||||||
|
|
||||||
When you declare `has_paper_trail` in your model, you get these methods:
|
When you declare `has_paper_trail` in your model, you get these methods:
|
||||||
|
|
||||||
|
@ -246,7 +250,9 @@ user_for_paper_trail
|
||||||
info_for_paper_trail
|
info_for_paper_trail
|
||||||
```
|
```
|
||||||
|
|
||||||
## Choosing Lifecycle Events To Monitor
|
## 2. Limiting What is Versioned, and When
|
||||||
|
|
||||||
|
### 2.a. Choosing Lifecycle Events To Monitor
|
||||||
|
|
||||||
You can choose which events to track with the `on` option. For example, to
|
You can choose which events to track with the `on` option. For example, to
|
||||||
ignore `create` events:
|
ignore `create` events:
|
||||||
|
@ -281,7 +287,7 @@ a.versions.size # 3
|
||||||
a.versions.last.event # 'update'
|
a.versions.last.event # 'update'
|
||||||
```
|
```
|
||||||
|
|
||||||
### Controlling the Order of AR Callbacks
|
#### Controlling the Order of AR Callbacks
|
||||||
|
|
||||||
The `has_paper_trail` method installs AR callbacks. If you need to control
|
The `has_paper_trail` method installs AR callbacks. If you need to control
|
||||||
their order, use the `paper_trail_on_*` methods.
|
their order, use the `paper_trail_on_*` methods.
|
||||||
|
@ -305,7 +311,7 @@ The `paper_trail_on_destroy` method can be further configured to happen
|
||||||
`:after`. In PaperTrail 5, the default will be `:before`, to support
|
`:after`. In PaperTrail 5, the default will be `:before`, to support
|
||||||
ActiveRecord 5. (see https://github.com/airblade/paper_trail/pull/683)
|
ActiveRecord 5. (see https://github.com/airblade/paper_trail/pull/683)
|
||||||
|
|
||||||
## Choosing When To Save New Versions
|
### 2.b. Choosing When To Save New Versions
|
||||||
|
|
||||||
You can choose the conditions when to add new versions with the `if` and
|
You can choose the conditions when to add new versions with the `if` and
|
||||||
`unless` options. For example, to save versions only for US non-draft
|
`unless` options. For example, to save versions only for US non-draft
|
||||||
|
@ -318,13 +324,13 @@ class Translation < ActiveRecord::Base
|
||||||
end
|
end
|
||||||
```
|
```
|
||||||
|
|
||||||
### Choosing Based on Changed Attributes
|
#### Choosing Based on Changed Attributes
|
||||||
|
|
||||||
Starting with PaperTrail 4.0, versions are saved during an after-callback. If
|
Starting with PaperTrail 4.0, versions are saved during an after-callback. If
|
||||||
you decide whether to save a new version based on changed attributes, please
|
you decide whether to save a new version based on changed attributes, please
|
||||||
use attribute_name_was instead of attribute_name.
|
use attribute_name_was instead of attribute_name.
|
||||||
|
|
||||||
## Choosing Attributes To Monitor
|
### 2.c. Choosing Attributes To Monitor
|
||||||
|
|
||||||
You can ignore changes to certain attributes like this:
|
You can ignore changes to certain attributes like this:
|
||||||
|
|
||||||
|
@ -411,11 +417,11 @@ class Article < ActiveRecord::Base
|
||||||
end
|
end
|
||||||
```
|
```
|
||||||
|
|
||||||
## Turning PaperTrail Off
|
### 2.d. Turning PaperTrail Off
|
||||||
|
|
||||||
PaperTrail is on by default, but sometimes you don't want to record versions.
|
PaperTrail is on by default, but sometimes you don't want to record versions.
|
||||||
|
|
||||||
### Per Process
|
#### Per Process
|
||||||
|
|
||||||
Turn PaperTrail off for all threads in a `ruby` process.
|
Turn PaperTrail off for all threads in a `ruby` process.
|
||||||
|
|
||||||
|
@ -432,7 +438,7 @@ There is also a rails config option that does the same thing.
|
||||||
config.paper_trail.enabled = false
|
config.paper_trail.enabled = false
|
||||||
```
|
```
|
||||||
|
|
||||||
### Per Request
|
#### Per Request
|
||||||
|
|
||||||
Add a `paper_trail_enabled_for_controller` method to your controller.
|
Add a `paper_trail_enabled_for_controller` method to your controller.
|
||||||
|
|
||||||
|
@ -444,14 +450,14 @@ class ApplicationController < ActionController::Base
|
||||||
end
|
end
|
||||||
```
|
```
|
||||||
|
|
||||||
### Per Class
|
#### Per Class
|
||||||
|
|
||||||
```ruby
|
```ruby
|
||||||
Widget.paper_trail_off!
|
Widget.paper_trail_off!
|
||||||
Widget.paper_trail_on!
|
Widget.paper_trail_on!
|
||||||
```
|
```
|
||||||
|
|
||||||
### Per Method
|
#### Per Method
|
||||||
|
|
||||||
You can call a method without creating a new version using `without_versioning`.
|
You can call a method without creating a new version using `without_versioning`.
|
||||||
It takes either a method name as a symbol:
|
It takes either a method name as a symbol:
|
||||||
|
@ -468,7 +474,7 @@ Or a block:
|
||||||
end
|
end
|
||||||
```
|
```
|
||||||
|
|
||||||
## Limiting the Number of Versions Created
|
### 2.e. Limiting the Number of Versions Created
|
||||||
|
|
||||||
Configure `version_limit` to cap the number of versions saved per record. This
|
Configure `version_limit` to cap the number of versions saved per record. This
|
||||||
does not apply to `create` events.
|
does not apply to `create` events.
|
||||||
|
@ -480,7 +486,9 @@ PaperTrail.config.version_limit = 3
|
||||||
PaperTrail.config.version_limit = nil
|
PaperTrail.config.version_limit = nil
|
||||||
```
|
```
|
||||||
|
|
||||||
## Reverting And Undeleting A Model
|
## 3. Working With Versions
|
||||||
|
|
||||||
|
### 3.a. Reverting And Undeleting A Model
|
||||||
|
|
||||||
PaperTrail makes reverting to a previous version easy:
|
PaperTrail makes reverting to a previous version easy:
|
||||||
|
|
||||||
|
@ -517,7 +525,7 @@ You could even use PaperTrail to implement an undo system, [Ryan Bates has!][3]
|
||||||
If your model uses [optimistic locking][1] don't forget to [increment your
|
If your model uses [optimistic locking][1] don't forget to [increment your
|
||||||
`lock_version`][2] before saving or you'll get a `StaleObjectError`.
|
`lock_version`][2] before saving or you'll get a `StaleObjectError`.
|
||||||
|
|
||||||
## Navigating Versions
|
### 3.b. Navigating Versions
|
||||||
|
|
||||||
You can call `previous_version` and `next_version` on an item to get it as it
|
You can call `previous_version` and `next_version` on an item to get it as it
|
||||||
was/became. Note that these methods reify the item for you.
|
was/became. Note that these methods reify the item for you.
|
||||||
|
@ -573,7 +581,7 @@ And you can perform `WHERE` queries for object versions based on attributes:
|
||||||
PaperTrail::Version.where_object(content: "Hello", title: "Article")
|
PaperTrail::Version.where_object(content: "Hello", title: "Article")
|
||||||
```
|
```
|
||||||
|
|
||||||
## Diffing Versions
|
### 3.c. Diffing Versions
|
||||||
|
|
||||||
There are two scenarios: diffing adjacent versions and diffing non-adjacent
|
There are two scenarios: diffing adjacent versions and diffing non-adjacent
|
||||||
versions.
|
versions.
|
||||||
|
@ -638,7 +646,7 @@ 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.
|
||||||
|
|
||||||
## Deleting Old Versions
|
### 3.d. 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
|
||||||
version is self-contained (see the Diffing section above for more) you can
|
version is self-contained (see the Diffing section above for more) you can
|
||||||
|
@ -652,7 +660,9 @@ sql> delete from versions where created_at < 2010-06-01;
|
||||||
PaperTrail::Version.delete_all ["created_at < ?", 1.week.ago]
|
PaperTrail::Version.delete_all ["created_at < ?", 1.week.ago]
|
||||||
```
|
```
|
||||||
|
|
||||||
## Finding Out Who Was Responsible For A Change
|
## 4. Saving More Information About Versions
|
||||||
|
|
||||||
|
### 4.a. Finding Out Who Was Responsible For A Change
|
||||||
|
|
||||||
Set `PaperTrail.whodunnit=`, and that value will be stored in the version's
|
Set `PaperTrail.whodunnit=`, and that value will be stored in the version's
|
||||||
`whodunnit` column.
|
`whodunnit` column.
|
||||||
|
@ -730,12 +740,12 @@ last_version.paper_trail_originator # 'Alice'
|
||||||
last_version.terminator # 'Bob'
|
last_version.terminator # 'Bob'
|
||||||
```
|
```
|
||||||
|
|
||||||
### Storing an ActiveRecord globalid in whodunnit
|
#### Storing an ActiveRecord globalid in whodunnit
|
||||||
|
|
||||||
If you would like `whodunnit` to return an `ActiveRecord` object instead of a
|
If you would like `whodunnit` to return an `ActiveRecord` object instead of a
|
||||||
string, please try the [paper_trail-globalid][37] gem.
|
string, please try the [paper_trail-globalid][37] gem.
|
||||||
|
|
||||||
## Associations
|
### 4.b. Associations
|
||||||
|
|
||||||
**Experimental feature**, see caveats below.
|
**Experimental feature**, see caveats below.
|
||||||
|
|
||||||
|
@ -841,7 +851,7 @@ widget.reload.wotsit # nil
|
||||||
rails until ActiveRecord 4.2 (https://github.com/rails/rails/pull/14359).
|
rails until ActiveRecord 4.2 (https://github.com/rails/rails/pull/14359).
|
||||||
1. PaperTrail can't restore an association properly if the association record
|
1. PaperTrail can't restore an association properly if the association record
|
||||||
can be updated to replace its parent model (by replacing the foreign key)
|
can be updated to replace its parent model (by replacing the foreign key)
|
||||||
1. Currently PaperTrail only support single `version_associations` table. The
|
1. Currently PaperTrail only supports a single `version_associations` table. The
|
||||||
implication is that you can only use a single table to store the versions for
|
implication is that you can only use a single table to store the versions for
|
||||||
all related models. Sorry for those who use multiple version tables.
|
all related models. Sorry for those who use multiple version tables.
|
||||||
1. PaperTrail only reifies the first level of associations, i.e., it does not
|
1. PaperTrail only reifies the first level of associations, i.e., it does not
|
||||||
|
@ -914,7 +924,7 @@ end
|
||||||
|
|
||||||
See [issue 113][16] for a discussion about this.
|
See [issue 113][16] for a discussion about this.
|
||||||
|
|
||||||
## Storing Metadata
|
### 4.c. Storing Metadata
|
||||||
|
|
||||||
You can store arbitrary model-level metadata alongside each version like this:
|
You can store arbitrary model-level metadata alongside each version like this:
|
||||||
|
|
||||||
|
@ -934,7 +944,7 @@ PaperTrail will call your proc with the current article and store the result in
|
||||||
the `author_id` column of the `versions` table.
|
the `author_id` column of the `versions` table.
|
||||||
Don't forget to add any such columns to your `versions` table.
|
Don't forget to add any such columns to your `versions` table.
|
||||||
|
|
||||||
### Advantages of Metadata
|
#### Advantages of Metadata
|
||||||
|
|
||||||
Why would you do this? In this example, `author_id` is an attribute of
|
Why would you do this? In this example, `author_id` is an attribute of
|
||||||
`Article` and PaperTrail will store it anyway in a serialized form in the
|
`Article` and PaperTrail will store it anyway in a serialized form in the
|
||||||
|
@ -948,7 +958,7 @@ those versions you want:
|
||||||
PaperTrail::Version.where(:author_id => author_id)
|
PaperTrail::Version.where(:author_id => author_id)
|
||||||
```
|
```
|
||||||
|
|
||||||
### Metadata from Controllers
|
#### Metadata from Controllers
|
||||||
|
|
||||||
You can also store any information you like from your controller. Override
|
You can also store any information you like from your controller. Override
|
||||||
the `info_for_paper_trail` method in your controller to return a hash whose keys
|
the `info_for_paper_trail` method in your controller to return a hash whose keys
|
||||||
|
@ -962,7 +972,7 @@ class ApplicationController
|
||||||
end
|
end
|
||||||
```
|
```
|
||||||
|
|
||||||
### Protected Attributes and Metadata
|
#### Protected Attributes and Metadata
|
||||||
|
|
||||||
If you are using rails 3 or the [protected_attributes][17] gem you must declare
|
If you are using rails 3 or the [protected_attributes][17] gem you must declare
|
||||||
your metadata columns to be `attr_accessible`.
|
your metadata columns to be `attr_accessible`.
|
||||||
|
@ -980,7 +990,9 @@ end
|
||||||
If you're using [strong_parameters][18] instead of [protected_attributes][17]
|
If you're using [strong_parameters][18] instead of [protected_attributes][17]
|
||||||
then there is no need to use `attr_accessible`.
|
then there is no need to use `attr_accessible`.
|
||||||
|
|
||||||
## Single Table Inheritance (STI)
|
## 5. ActiveRecord
|
||||||
|
|
||||||
|
### 5.a. Single Table Inheritance (STI)
|
||||||
|
|
||||||
PaperTrail supports [Single Table Inheritance][39], and even supports an
|
PaperTrail supports [Single Table Inheritance][39], and even supports an
|
||||||
un-versioned base model, as of 23ffbdc7e1.
|
un-versioned base model, as of 23ffbdc7e1.
|
||||||
|
@ -997,30 +1009,25 @@ end
|
||||||
However, there is a known issue when reifying [associations](#associations),
|
However, there is a known issue when reifying [associations](#associations),
|
||||||
see https://github.com/airblade/paper_trail/issues/594
|
see https://github.com/airblade/paper_trail/issues/594
|
||||||
|
|
||||||
## Overriding the `versions` method
|
### 5.b. Configuring the `versions` Association
|
||||||
|
|
||||||
Overriding the `versions` method is officially not supported, but you can
|
You may configure the name of the `versions` association by passing
|
||||||
change the name of that association. Because `versions` returns an
|
a different name to `has_paper_trail`.
|
||||||
`ActiveRecord::Relation` object, changes to that method will result in changes
|
|
||||||
both to how records are retrieved _and_ how records are created.
|
|
||||||
|
|
||||||
If you absolutely must override this method to maintain your object's API,
|
|
||||||
you can do so safely by changing the name of the association.
|
|
||||||
|
|
||||||
```ruby
|
```ruby
|
||||||
module News
|
class Post < ActiveRecord::Base
|
||||||
class Post < ActiveRecord::Base
|
has_paper_trail class_name: 'Version', versions: :drafts
|
||||||
has_paper_trail class_name: 'Version', versions: :base_versions
|
|
||||||
|
|
||||||
def versions
|
|
||||||
types = ['Post', 'News::Post']
|
|
||||||
@versions ||= Version.where(item_id: id, item_type: types)
|
|
||||||
end
|
|
||||||
end
|
|
||||||
end
|
end
|
||||||
|
|
||||||
|
Post.new.versions # => NoMethodError
|
||||||
```
|
```
|
||||||
|
|
||||||
## Custom Version Classes
|
Overriding (instead of configuring) the `versions` method is not supported.
|
||||||
|
Overriding associations is not recommended in general.
|
||||||
|
|
||||||
|
## 6. Extensibility
|
||||||
|
|
||||||
|
### 6.a. Custom Version Classes
|
||||||
|
|
||||||
You can specify custom version subclasses with the `:class_name` option:
|
You can specify custom version subclasses with the `:class_name` option:
|
||||||
|
|
||||||
|
@ -1037,13 +1044,13 @@ end
|
||||||
|
|
||||||
Unlike ActiveRecord's `class_name`, you'll have to supply the complete module path to the class (e.g. `Foo::BarVersion` if your class is inside the module `Foo`).
|
Unlike ActiveRecord's `class_name`, you'll have to supply the complete module path to the class (e.g. `Foo::BarVersion` if your class is inside the module `Foo`).
|
||||||
|
|
||||||
### Advantages
|
#### Advantages
|
||||||
|
|
||||||
1. For models which have a lot of versions, storing each model's versions in a
|
1. For models which have a lot of versions, storing each model's versions in a
|
||||||
separate table can improve the performance of certain database queries.
|
separate table can improve the performance of certain database queries.
|
||||||
1. Store different version [metadata](#storing-metadata) for different models.
|
1. Store different version [metadata](#storing-metadata) for different models.
|
||||||
|
|
||||||
### Configuration
|
#### Configuration
|
||||||
|
|
||||||
If you are using Postgres, you should also define the sequence that your custom
|
If you are using Postgres, you should also define the sequence that your custom
|
||||||
version class will use:
|
version class will use:
|
||||||
|
@ -1089,7 +1096,7 @@ class Post < ActiveRecord::Base
|
||||||
end
|
end
|
||||||
```
|
```
|
||||||
|
|
||||||
## Custom Serializer
|
### 6.b. 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
|
||||||
this with the serializer config option:
|
this with the serializer config option:
|
||||||
|
@ -1104,7 +1111,7 @@ method. These serializers are included in the gem for your convenience:
|
||||||
* [PaperTrail::Serializers::YAML][24] - Default
|
* [PaperTrail::Serializers::YAML][24] - Default
|
||||||
* [PaperTrail::Serializers::JSON][25]
|
* [PaperTrail::Serializers::JSON][25]
|
||||||
|
|
||||||
### PostgreSQL JSON column type support
|
#### PostgreSQL JSON column type support
|
||||||
|
|
||||||
If you use PostgreSQL, and would like to store your `object` (and/or
|
If you use PostgreSQL, and would like to store your `object` (and/or
|
||||||
`object_changes`) data in a column of [type `json` or type `jsonb`][26], specify
|
`object_changes`) data in a column of [type `json` or type `jsonb`][26], specify
|
||||||
|
@ -1122,7 +1129,7 @@ end
|
||||||
If you use the PostgreSQL `json` or `jsonb` column type, you do not need
|
If you use the PostgreSQL `json` or `jsonb` column type, you do not need
|
||||||
to specify a `PaperTrail.serializer`.
|
to specify a `PaperTrail.serializer`.
|
||||||
|
|
||||||
#### Convert existing YAML data to JSON
|
##### Convert existing YAML data to JSON
|
||||||
|
|
||||||
If you've been using PaperTrail for a while with the default YAML serializer
|
If you've been using PaperTrail for a while with the default YAML serializer
|
||||||
and you want to switch to JSON or JSONB, you're in a bit of a bind because
|
and you want to switch to JSON or JSONB, you're in a bit of a bind because
|
||||||
|
@ -1174,7 +1181,7 @@ remove_column :versions, :old_object
|
||||||
If you use the optional `object_changes` column, don't forget to convert it
|
If you use the optional `object_changes` column, don't forget to convert it
|
||||||
also, using the same technique.
|
also, using the same technique.
|
||||||
|
|
||||||
#### Convert a Column from Text to JSON
|
##### Convert a Column from Text to JSON
|
||||||
|
|
||||||
If your `object` column already contains JSON data, and you want to change its
|
If your `object` column already contains JSON data, and you want to change its
|
||||||
data type to `json` or `jsonb`, you can use the following [DDL][36]. Of course,
|
data type to `json` or `jsonb`, you can use the following [DDL][36]. Of course,
|
||||||
|
@ -1203,12 +1210,12 @@ class ConvertVersionsObjectToJson < ActiveRecord::Migration
|
||||||
end
|
end
|
||||||
```
|
```
|
||||||
|
|
||||||
## Testing
|
## 7. Testing
|
||||||
|
|
||||||
You may want to turn PaperTrail off to speed up your tests. See [Turning
|
You may want to turn PaperTrail off to speed up your tests. See [Turning
|
||||||
PaperTrail Off](#turning-papertrail-off) above.
|
PaperTrail Off](#turning-papertrail-off) above.
|
||||||
|
|
||||||
### Minitest
|
### 7.a. Minitest
|
||||||
|
|
||||||
First, disable PT for the entire `ruby` process.
|
First, disable PT for the entire `ruby` process.
|
||||||
|
|
||||||
|
@ -1248,7 +1255,7 @@ test "something that needs versioning" do
|
||||||
end
|
end
|
||||||
```
|
```
|
||||||
|
|
||||||
### RSpec
|
### 7.b. RSpec
|
||||||
|
|
||||||
PaperTrail provides a helper, `paper_trail/frameworks/rspec.rb`, that works with
|
PaperTrail provides a helper, `paper_trail/frameworks/rspec.rb`, that works with
|
||||||
[RSpec][27] to make it easier to control when `PaperTrail` is enabled during
|
[RSpec][27] to make it easier to control when `PaperTrail` is enabled during
|
||||||
|
@ -1338,7 +1345,7 @@ matcher
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Cucumber
|
### 7.c. Cucumber
|
||||||
|
|
||||||
PaperTrail provides a helper for [Cucumber][28] that works similar to the RSpec
|
PaperTrail provides a helper for [Cucumber][28] that works similar to the RSpec
|
||||||
helper.If you wish to use the helper, you will need to require in your cucumber
|
helper.If you wish to use the helper, you will need to require in your cucumber
|
||||||
|
@ -1371,7 +1378,7 @@ test to help prevent data spillover between tests. If you are using PaperTrail
|
||||||
with Rails, the helper will automatically set the `PaperTrail.controller_info`
|
with Rails, the helper will automatically set the `PaperTrail.controller_info`
|
||||||
value to `{}` as well, again, to help prevent data spillover between tests.
|
value to `{}` as well, again, to help prevent data spillover between tests.
|
||||||
|
|
||||||
### Spork
|
### 7.d. Spork
|
||||||
|
|
||||||
If you wish to use the `RSpec` or `Cucumber` helpers with [Spork][29], you will
|
If you wish to use the `RSpec` or `Cucumber` helpers with [Spork][29], you will
|
||||||
need to manually require the helper(s) in your `prefork` block on your test
|
need to manually require the helper(s) in your `prefork` block on your test
|
||||||
|
@ -1394,7 +1401,7 @@ Spork.prefork do
|
||||||
end
|
end
|
||||||
```
|
```
|
||||||
|
|
||||||
### Zeus or Spring
|
### 7.e. Zeus or Spring
|
||||||
|
|
||||||
If you wish to use the `RSpec` or `Cucumber` helpers with [Zeus][30] or
|
If you wish to use the `RSpec` or `Cucumber` helpers with [Zeus][30] or
|
||||||
[Spring][31], you will need to manually require the helper(s) in your test
|
[Spring][31], you will need to manually require the helper(s) in your test
|
||||||
|
@ -1410,25 +1417,9 @@ require 'rspec/rails'
|
||||||
require 'paper_trail/frameworks/rspec'
|
require 'paper_trail/frameworks/rspec'
|
||||||
```
|
```
|
||||||
|
|
||||||
## Testing PaperTrail
|
## 8. Sinatra
|
||||||
|
|
||||||
Paper Trail has facilities to test against Postgres, Mysql and SQLite. To switch
|
To configure PaperTrail for usage with [Sinatra][12], your `Sinatra`
|
||||||
between DB engines you will need to export the DB variable for the engine you
|
|
||||||
wish to test against.
|
|
||||||
|
|
||||||
Though be aware we do not have the ability to create the db's (except sqlite) for
|
|
||||||
you. You can look at .travis.yml before_script for an example of how to create
|
|
||||||
the db's needed.
|
|
||||||
|
|
||||||
```
|
|
||||||
export DB=postgres
|
|
||||||
export DB=mysql
|
|
||||||
export DB=sqlite # this is default
|
|
||||||
```
|
|
||||||
|
|
||||||
## Sinatra
|
|
||||||
|
|
||||||
In order to configure PaperTrail for usage with [Sinatra][12], your `Sinatra`
|
|
||||||
app must be using `ActiveRecord` 3 or 4. It is also recommended to use the
|
app must be using `ActiveRecord` 3 or 4. It is also recommended to use the
|
||||||
[Sinatra ActiveRecord Extension][13] or something similar for managing your
|
[Sinatra ActiveRecord Extension][13] or something similar for managing your
|
||||||
applications `ActiveRecord` connection in a manner similar to the way `Rails`
|
applications `ActiveRecord` connection in a manner similar to the way `Rails`
|
||||||
|
|
Loading…
Reference in New Issue