From 7d60a41e131983af5e232b4c0e1118b6513cbc18 Mon Sep 17 00:00:00 2001 From: Nathan Date: Thu, 25 Aug 2016 12:31:03 -0600 Subject: [PATCH] Generate an initializer with `track_associations`, improve docs (#854) * create initializer in generator and improve docs * Remove upgrading section from README * rework configuration section --- README.md | 50 ++++++++++++++----- .../paper_trail/default_initializer.rb | 0 .../paper_trail/install_generator.rb | 10 +++- 3 files changed, 46 insertions(+), 14 deletions(-) create mode 100644 lib/generators/paper_trail/default_initializer.rb diff --git a/README.md b/README.md index b5238c77..b5e8a162 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,7 @@ has been destroyed. - [1.b. Installation](#1b-installation) - [1.c. Basic Usage](#1c-basic-usage) - [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.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) @@ -68,7 +69,7 @@ has been destroyed. `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 @@ -253,6 +254,18 @@ user_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.a. Choosing Lifecycle Events To Monitor @@ -755,16 +768,26 @@ string, please try the [paper_trail-globalid][37] gem. below. 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 -`version_associations` table, either at installation time with the `rails -generate paper_trail:install --with-associations` option or manually. PaperTrail -will store in that 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. +Has-Many-Through. In order to do this, you will need to do two things: + +1. Create a `version_associations` table +2. Set `PaperTrail.config.track_associations = true` (e.g. in an initializer) + +Both will be done for you automatically if you install PaperTrail with the +`--with_associations` option +(e.g. `rails generate paper_trail:install --with-associations`) + +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 => 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 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 generate paper_trail:install --help`, but a copy is included here for convenience. @@ -1056,7 +1080,7 @@ Runtime options: -q, [--quiet], [--no-quiet] # Suppress status output -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 diff --git a/lib/generators/paper_trail/default_initializer.rb b/lib/generators/paper_trail/default_initializer.rb new file mode 100644 index 00000000..e69de29b diff --git a/lib/generators/paper_trail/install_generator.rb b/lib/generators/paper_trail/install_generator.rb index 3073d5a1..3ef0fdc0 100644 --- a/lib/generators/paper_trail/install_generator.rb +++ b/lib/generators/paper_trail/install_generator.rb @@ -20,7 +20,8 @@ module PaperTrail 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 add_paper_trail_migration("create_versions") @@ -31,6 +32,13 @@ module PaperTrail 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) ::ActiveRecord::Generators::Base.next_migration_number(dirname) end