From 593da233bf16f4e25bb75f9f4d1e3781a7e089c2 Mon Sep 17 00:00:00 2001 From: Jared Beck Date: Sun, 4 Mar 2018 00:24:11 -0500 Subject: [PATCH] Docs: Dirty, controllers [ci skip] --- CHANGELOG.md | 5 ++-- README.md | 1 + .../frameworks/rails/controller.rb | 19 ++++++++++++ lib/paper_trail/model_config.rb | 6 ++++ lib/paper_trail/record_trail.rb | 30 ++++++++++++++++++- 5 files changed, 58 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 71f4fbf8..fac2bba9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,8 +19,9 @@ recommendations of [keepachangelog.com](http://keepachangelog.com/). - Removed deprecated `Version#originator`, use `#paper_trail_originator` - Using paper_trail.on_destroy(:after) with ActiveRecord's belongs_to_required_by_default will produce an error instead of a warning. -- Removed `warn_about_not_setting_whodunnit` controller method. Please remove - callbacks like `skip_after_action :warn_about_not_setting_whodunnit`. +- Removed the `warn_about_not_setting_whodunnit` controller method. This will + only be a problem for you if you are skipping it, eg. + `skip_after_action :warn_about_not_setting_whodunnit`, which few people did. ### Deprecated diff --git a/README.md b/README.md index 02b1fc7e..cfc541ad 100644 --- a/README.md +++ b/README.md @@ -483,6 +483,7 @@ Add a `paper_trail_enabled_for_controller` method to your controller. ```ruby class ApplicationController < ActionController::Base def paper_trail_enabled_for_controller + # Don't omit `super` without a good reason. super && request.user_agent != 'Disable User-Agent' end end diff --git a/lib/paper_trail/frameworks/rails/controller.rb b/lib/paper_trail/frameworks/rails/controller.rb index 5ec4de4a..85b91d27 100644 --- a/lib/paper_trail/frameworks/rails/controller.rb +++ b/lib/paper_trail/frameworks/rails/controller.rb @@ -20,6 +20,8 @@ module PaperTrail # # Override this method in your controller to call a different # method, e.g. `current_person`, or anything you like. + # + # @api public def user_for_paper_trail return unless defined?(current_user) ActiveSupport::VERSION::MAJOR >= 4 ? current_user.try!(:id) : current_user.try(:id) @@ -45,6 +47,8 @@ module PaperTrail # Use the `:meta` option to # `PaperTrail::Model::ClassMethods.has_paper_trail` to store any extra # model-level data you need. + # + # @api public def info_for_paper_trail {} end @@ -54,6 +58,15 @@ module PaperTrail # # Override this method in your controller to specify when PaperTrail # should be off. + # + # ``` + # def paper_trail_enabled_for_controller + # # Don't omit `super` without a good reason. + # super && request.user_agent != 'Disable User-Agent' + # end + # ``` + # + # @api public def paper_trail_enabled_for_controller ::PaperTrail.enabled? end @@ -62,11 +75,15 @@ module PaperTrail # Tells PaperTrail whether versions should be saved in the current # request. + # + # @api public def set_paper_trail_enabled_for_controller ::PaperTrail.request.enabled_for_controller = paper_trail_enabled_for_controller end # Tells PaperTrail who is responsible for any changes that occur. + # + # @api public def set_paper_trail_whodunnit if ::PaperTrail.request.enabled_for_controller? ::PaperTrail.request.whodunnit = user_for_paper_trail @@ -75,6 +92,8 @@ module PaperTrail # Tells PaperTrail any information from the controller you want to store # alongside any changes that occur. + # + # @api public def set_paper_trail_controller_info if ::PaperTrail.request.enabled_for_controller? ::PaperTrail.request.controller_info = info_for_paper_trail diff --git a/lib/paper_trail/model_config.rb b/lib/paper_trail/model_config.rb index 1aba7e76..3490681c 100644 --- a/lib/paper_trail/model_config.rb +++ b/lib/paper_trail/model_config.rb @@ -63,6 +63,8 @@ module PaperTrail end # Adds a callback that records a version after a "create" event. + # + # @api public def on_create @model_class.after_create { |r| r.paper_trail.record_create if r.paper_trail.save_version? @@ -72,6 +74,8 @@ module PaperTrail end # Adds a callback that records a version before or after a "destroy" event. + # + # @api public def on_destroy(recording_order = "before") unless %w[after before].include?(recording_order.to_s) raise ArgumentError, 'recording order can only be "after" or "before"' @@ -91,6 +95,8 @@ module PaperTrail end # Adds a callback that records a version after an "update" event. + # + # @api public def on_update @model_class.before_save { |r| r.paper_trail.reset_timestamp_attrs_for_update_if_needed diff --git a/lib/paper_trail/record_trail.rb b/lib/paper_trail/record_trail.rb index 03214a3d..3859b59f 100644 --- a/lib/paper_trail/record_trail.rb +++ b/lib/paper_trail/record_trail.rb @@ -27,6 +27,7 @@ module PaperTrail # > instead, similar to the other branch in reify_has_one. # > -Sean Griffin (https://github.com/airblade/paper_trail/pull/899) # + # @api private def appear_as_new_record @record.instance_eval { alias :old_new_record? :new_record? @@ -137,6 +138,8 @@ module PaperTrail end # Updates `data` from the model's `meta` option and from `controller_info`. + # Metadata is always recorded; that means all three events (create, update, + # destroy) and `update_columns`. # @api private def merge_metadata_into(data) merge_metadata_from_model_into(data) @@ -204,6 +207,8 @@ module PaperTrail # Returns hash of attributes (with appropriate attributes serialized), # omitting attributes to be skipped. + # + # @api private def object_attrs_for_paper_trail attrs = attributes_before_change.except(*@record.paper_trail_options[:skip]) AttributeSerializers::ObjectAttribute.new(@record.class).serialize(attrs) @@ -211,11 +216,15 @@ module PaperTrail end # Returns who put `@record` into its current state. + # + # @api public def originator (source_version || versions.last).try(:whodunnit) end # Returns the object (not a Version) as it was most recently. + # + # @api public def previous_version (source_version ? source_version.previous : versions.last).try(:reify) end @@ -300,7 +309,9 @@ module PaperTrail @in_after_callback = false end - # Returns data for record_update + # Used during `record_update`, returns a hash of data suitable for an AR + # `create`. That is, all the attributes of the nascent `Version` record. + # # @api private def data_for_update data = { @@ -351,6 +362,7 @@ module PaperTrail # column, then a hash can be used in the assignment, otherwise the column # is a `text` column, and we must perform the serialization here, using # `PaperTrail.serializer`. + # # @api private def recordable_object if @record.class.paper_trail.version_class.object_col_is_json? @@ -365,6 +377,7 @@ module PaperTrail # a postgres `json` column, then a hash can be used in the assignment, # otherwise the column is a `text` column, and we must perform the # serialization here, using `PaperTrail.serializer`. + # # @api private def recordable_object_changes(changes) if @record.class.paper_trail.version_class.object_changes_col_is_json? @@ -432,6 +445,9 @@ module PaperTrail # creates a version. A version is created regardless of options such as # `:on`, `:if`, or `:unless`. # + # This is an "update" event. That is, we record the same data we would in + # the case of a normal AR `update`. + # # TODO: look into leveraging the `after_touch` callback from # `ActiveRecord` to allow the regular `touch` method to generate a version # as normal. May make sense to switch the `record_update` method to @@ -520,6 +536,9 @@ module PaperTrail data[:transaction_id] = PaperTrail.request.transaction_id end + # Rails 5.1 changed the API of `ActiveRecord::Dirty`. See + # https://github.com/airblade/paper_trail/pull/899 + # # @api private def attribute_changed_in_latest_version?(attr_name) if @in_after_callback && RAILS_GTE_5_1 @@ -529,6 +548,8 @@ module PaperTrail end end + # Rails 5.1 changed the API of `ActiveRecord::Dirty`. See + # https://github.com/airblade/paper_trail/pull/899 # @api private def attribute_in_previous_version(attr_name) if @in_after_callback && RAILS_GTE_5_1 @@ -538,6 +559,9 @@ module PaperTrail end end + # Rails 5.1 changed the API of `ActiveRecord::Dirty`. See + # https://github.com/airblade/paper_trail/pull/899 + # # @api private def changed_in_latest_version if @in_after_callback && RAILS_GTE_5_1 @@ -547,6 +571,9 @@ module PaperTrail end end + # Rails 5.1 changed the API of `ActiveRecord::Dirty`. See + # https://github.com/airblade/paper_trail/pull/899 + # # @api private def changes_in_latest_version if @in_after_callback && RAILS_GTE_5_1 @@ -557,6 +584,7 @@ module PaperTrail end # Given a HABTM association, returns an array of ids. + # # @api private def habtm_assoc_ids(habtm_assoc) current = @record.send(habtm_assoc.name).to_a.map(&:id) # TODO: `pluck` would use less memory