Generate an initializer with `track_associations`, improve docs (#854)
* create initializer in generator and improve docs * Remove upgrading section from README * rework configuration section
This commit is contained in:
parent
5a88c96141
commit
7d60a41e13
50
README.md
50
README.md
|
@ -24,6 +24,7 @@ has been destroyed.
|
||||||
- [1.b. Installation](#1b-installation)
|
- [1.b. Installation](#1b-installation)
|
||||||
- [1.c. Basic Usage](#1c-basic-usage)
|
- [1.c. Basic Usage](#1c-basic-usage)
|
||||||
- [1.d. API Summary](#1d-api-summary)
|
- [1.d. API Summary](#1d-api-summary)
|
||||||
|
- [1.e. Configuration](#1e-configuration)
|
||||||
- [2. Limiting What is Versioned, and When](#2-limiting-what-is-versioned-and-when)
|
- [2. Limiting What is Versioned, and When](#2-limiting-what-is-versioned-and-when)
|
||||||
- [2.a. Choosing Lifecycle Events To Monitor](#2a-choosing-lifecycle-events-to-monitor)
|
- [2.a. Choosing Lifecycle Events To Monitor](#2a-choosing-lifecycle-events-to-monitor)
|
||||||
- [2.b. Choosing When To Save New Versions](#2b-choosing-when-to-save-new-versions)
|
- [2.b. Choosing When To Save New Versions](#2b-choosing-when-to-save-new-versions)
|
||||||
|
@ -68,7 +69,7 @@ has been destroyed.
|
||||||
|
|
||||||
`gem 'paper_trail'`
|
`gem 'paper_trail'`
|
||||||
|
|
||||||
1. Add a `versions` table to your database.
|
1. Add a `versions` table to your database and an initializer file for configuration:
|
||||||
|
|
||||||
```
|
```
|
||||||
bundle exec rails generate paper_trail:install
|
bundle exec rails generate paper_trail:install
|
||||||
|
@ -253,6 +254,18 @@ user_for_paper_trail
|
||||||
info_for_paper_trail
|
info_for_paper_trail
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### 1.e. Configuration
|
||||||
|
|
||||||
|
Many aspects of PaperTrail are configurable for individual models; typically
|
||||||
|
this is achieved by passing options to the `has_paper_trail` method within
|
||||||
|
a given model.
|
||||||
|
|
||||||
|
Some aspects of PaperTrail are configured globally for all models. These
|
||||||
|
settings are assigned directly on the `PaperTrail.config` object.
|
||||||
|
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`.
|
||||||
|
|
||||||
## 2. Limiting What is Versioned, and When
|
## 2. Limiting What is Versioned, and When
|
||||||
|
|
||||||
### 2.a. Choosing Lifecycle Events To Monitor
|
### 2.a. Choosing Lifecycle Events To Monitor
|
||||||
|
@ -755,16 +768,26 @@ string, please try the [paper_trail-globalid][37] gem.
|
||||||
below.
|
below.
|
||||||
|
|
||||||
PaperTrail can restore three types of associations: Has-One, Has-Many, and
|
PaperTrail can restore three types of associations: Has-One, Has-Many, and
|
||||||
Has-Many-Through. In order to do this, you will need to create a
|
Has-Many-Through. In order to do this, you will need to do two things:
|
||||||
`version_associations` table, either at installation time with the `rails
|
|
||||||
generate paper_trail:install --with-associations` option or manually. PaperTrail
|
1. Create a `version_associations` table
|
||||||
will store in that table additional information to correlate versions of the
|
2. Set `PaperTrail.config.track_associations = true` (e.g. in an initializer)
|
||||||
association and versions of the model when the associated record is changed.
|
|
||||||
When reifying the model, PaperTrail can use this table, together with the
|
Both will be done for you automatically if you install PaperTrail with the
|
||||||
`transaction_id` to find the correct version of the association and reify it.
|
`--with_associations` option
|
||||||
The `transaction_id` is a unique id for version records created in the same
|
(e.g. `rails generate paper_trail:install --with-associations`)
|
||||||
transaction. It is used to associate the version of the model and the version of
|
|
||||||
the association that are created in the same transaction.
|
If you want to add this functionality after the initial installation, you will
|
||||||
|
need to create the `version_associations` table manually, and you will need to
|
||||||
|
ensure that `PaperTrail.config.track_associations = true` is set.
|
||||||
|
|
||||||
|
PaperTrail will store in the `version_associations` table additional information
|
||||||
|
to correlate versions of the association and versions of the model when the
|
||||||
|
associated record is changed. When reifying the model, PaperTrail can use this
|
||||||
|
table, together with the `transaction_id` to find the correct version of the
|
||||||
|
association and reify it. The `transaction_id` is a unique id for version records
|
||||||
|
created in the same transaction. It is used to associate the version of the model
|
||||||
|
and the version of the association that are created in the same transaction.
|
||||||
|
|
||||||
To restore Has-One associations as they were at the time, pass option `:has_one
|
To restore Has-One associations as they were at the time, pass option `:has_one
|
||||||
=> true` to `reify`. To restore Has-Many and Has-Many-Through associations, use
|
=> true` to `reify`. To restore Has-Many and Has-Many-Through associations, use
|
||||||
|
@ -1037,7 +1060,8 @@ Overriding associations is not recommended in general.
|
||||||
### 5.c. Generators
|
### 5.c. Generators
|
||||||
|
|
||||||
PaperTrail has one generator, `paper_trail:install`. It writes, but does not
|
PaperTrail has one generator, `paper_trail:install`. It writes, but does not
|
||||||
run, a migration file. This migration adds (at least) the `versions` table. The
|
run, a migration file. It also creates a PaperTrail configuration intializer.
|
||||||
|
The migration adds (at least) the `versions` table. The
|
||||||
most up-to-date documentation for this generator can be found by running `rails
|
most up-to-date documentation for this generator can be found by running `rails
|
||||||
generate paper_trail:install --help`, but a copy is included here for
|
generate paper_trail:install --help`, but a copy is included here for
|
||||||
convenience.
|
convenience.
|
||||||
|
@ -1056,7 +1080,7 @@ Runtime options:
|
||||||
-q, [--quiet], [--no-quiet] # Suppress status output
|
-q, [--quiet], [--no-quiet] # Suppress status output
|
||||||
-s, [--skip], [--no-skip] # Skip files that already exist
|
-s, [--skip], [--no-skip] # Skip files that already exist
|
||||||
|
|
||||||
Generates (but does not run) a migration to add a versions table.
|
Generates (but does not run) a migration to add a versions table. Also generates an initializer file for configuring PaperTrail
|
||||||
```
|
```
|
||||||
|
|
||||||
## 6. Extensibility
|
## 6. Extensibility
|
||||||
|
|
|
@ -20,7 +20,8 @@ module PaperTrail
|
||||||
desc: "Store transactional IDs to support association restoration"
|
desc: "Store transactional IDs to support association restoration"
|
||||||
)
|
)
|
||||||
|
|
||||||
desc "Generates (but does not run) a migration to add a versions table."
|
desc "Generates (but does not run) a migration to add a versions table." \
|
||||||
|
" Also generates an initializer file for configuring PaperTrail"
|
||||||
|
|
||||||
def create_migration_file
|
def create_migration_file
|
||||||
add_paper_trail_migration("create_versions")
|
add_paper_trail_migration("create_versions")
|
||||||
|
@ -31,6 +32,13 @@ module PaperTrail
|
||||||
end
|
end
|
||||||
end
|
end
|
||||||
|
|
||||||
|
def create_initializer
|
||||||
|
create_file(
|
||||||
|
"config/initializers/paper_trail.rb",
|
||||||
|
"PaperTrail.config.track_associations = #{!!options.with_associations?}"
|
||||||
|
)
|
||||||
|
end
|
||||||
|
|
||||||
def self.next_migration_number(dirname)
|
def self.next_migration_number(dirname)
|
||||||
::ActiveRecord::Generators::Base.next_migration_number(dirname)
|
::ActiveRecord::Generators::Base.next_migration_number(dirname)
|
||||||
end
|
end
|
||||||
|
|
Loading…
Reference in New Issue